LE792388 - Electronic component Microchip - Free user manual and instructions

USER MANUAL LE792388 Microchip

Issue Date: June 2016

CONFIDENTIAL RELEASE UNDER NDA

This page left intentionally blank

TABLE OF CONTENTS

CHAPTER 1 INTRODUCTION....1

1.1 About this User's Guide 1

1.1.1 Chapter Overview 1
1.1.2 Frequently Used Terms.... 2
1.1.3 Documentation Conventions 2

1.2 VP-API-II Overview 2

1.2.1 Features 2
1.2.2 Architecture 3
1.2.3 Supported Hardware Configurations 5
1.2.4 VP-API-II Function Summary 7
1.2.5 Basic VP-API-II Data Types 9
1.2.6 VP-API-II Function Return Type 10

1.3 API-II Source Version Number 11
1.4 Application Notes 12
1.5 Technical Support 12

CHAPTER 2 PROFILES....13

2.1 Overview 13
2.2 Profile Types 13
2.3 Profile Tables 14
2.4 Profile Functions.... 15

CHAPTER 3 SYSTEM CONFIGURATION FUNCTIONS....17

3.1 Overview 17
3.2 Objects and Contexts.... 17
3.3 Multi-Tasking Applications 18

3.3.1 Multi-Tasking with Protected Memory 19

3.4 Function Descriptions....21

3.4.1 VpMakeDeviceObject() 21
3.4.2 VpMakeLineObject() 22
3.4.3 VpMakeDeviceCtx() 23
3.4.4 VpMakeLineCtx() 24
3.4.5 VpFreeLineCtx() 25
3.4.6 VpGetDeviceInfo() 26
3.4.7 VpGetLineInfo() 27
3.4.8 VpMapLineld() 28

CHAPTER 4 OPTIONS....29

4.1 Overview 29
4.2 Option Summary 29
4.3 Option Descriptions 31

4.3.1 VP_DEVICE_OPTION_ID_PULSE 31
4.3.2 VP_DEVICE_OPTION_ID_CRITICAL_FLT 33
4.3.3 VP OPTION ID ZERO CROSS 33
4.3.4 VP_OPTION_ID_PULSE_MODE 34
4.3.5 VP_OPTION_ID_TIMESLOT 34
4.3.6 VP_OPTION_ID_CODEC 35
4.3.7 VP_OPTION_ID_PCM_HWY 35

4.3.8 VP_OPTION_ID_LOOPBACK 35

4.3.9 VP OPTION ID LINE STATE.... 36

4.3.10 VP_OPTION_ID_EVENT_MASK 37

4.3.11 VP_OPTION_ID_RING_CNTRL 38

4.3.12 VP OPTION ID DTMF MODE 39

4.3.13 VP_OPTION_ID_PCM_TXRX_CNTRL.... 40

4.3.14 VP_DEVICE_OPTION_ID_DEV_IO_CFG 40

4.3.15 VP OPTION ID LINE IO CFG.... 41

4.3.16 VP OPTION ID DTMF SPEC.... 43

4.3.17 VP_DEVICE_OPTION_ID_PARK_MODE 43

4.3.18 VP_OPTION_ID_PULSE 44

4.3.19 VP_OPTION_ID_DCFEED_SLOPE 46

4.3.20 VP OPTION ID DEBUG SELECT 46

4.3.21 VP OPTION ID HOOK DETECT MODE 47

4.3.22 VP_DEVICE_OPTION_ID_PCM_SIG_CTL 48

4.3.23 VP_OPTION_ID_LINESTATE_CTL_MODE 49

CHAPTER 5 EVENTS.... 51

5.1 Overview 51

5.2 Event Summary 53

5.2.1 Event Specificity 55

5.3 Fault Events 56

5.5 Response Events 63

5.5.1 VP LINE EVID LLCMD TX CMP....63

5.5.2 VP_LINE_EVID_LLCMD_RX_CMP 63

5.5.3 VP DEV EVID DNSTR MBOX....63

5.5.4 VP LINE EVID RD OPTION 64

5.5.5 VP LINE EVID RD LOOP 64

5.5.6 VP EVID CAL CMP 66

5.5.7 VP_EVID_CAL_BUSY 66

5.5.8 VP LINE EVID GAIN CMP 67

5.5.9 VP_DEV_EVID_DEV_INIT_CMP 67

5.5.10 VP_LINE_EVID_LINE_INIT_CMP....68

5.5.11 VP_DEV_EVID_IO_ACCESS_CMP 68
5.5.12 VP LINE EVID LINE IO RD CMP 68
5.5.13 VP_LINE_EVID_LINE_IO_WR_CMP 69
5.5.14 VP_LINE_EVID_QUERY_CMP....69

5.6 Test Events 70

5.6.1 VP_LINE_EVID_TEST_CMP 70
5.6.2 VP_LINE_EVID_DTONE_DET 70
5.6.3 VP LINE EVID DTONE LOSS 70

5.7 Process Events 71

5.7.1 VP LINE EVID MTR CMP 71
5.7.2 VP_LINE_EVID_MTR_ABORT 71
5.7.3 VP LINE EVID MTR CAD 71
5.7.4 VP_LINE_EVID_MTR_ROLLOVER 72
5.7.5 VP_LINE EVID CID DATA 72
5.7.6 VP_LINE_EVID_RING_CAD.... 73
5.7.7 VP_LINE_EVID_SIGNAL_CMP 73
5.7.8 VP LINE EVID TONE CAD 73
5.7.9 VP_LINE_EVID_GEN_TIMER 74
5.7.10 VP_LINE_EVID_USER 74

CHAPTER 6 INITIALIZATION FUNCTIONS 75

6.1 Overview 75
6.2 Function Descriptions....76

6.2.1 VpInitDevice() 77
6.2.2 VpInitLine() 79
6.2.3 VpConfigLine() 80
6.2.4 VpCalCodec() 81
6.2.5 VpCalLine() 82
6.2.6 VpInitRing() 83
6.2.7 VpInitCid() 85
6.2.8 VpInitMeter() 86
6.2.9 VpInitProfile() 87
6.2.10 VpSetBatteries() 88

CHAPTER 7 CONTROL FUNCTIONS....89

7.1 Overview 89
7.2 Function Descriptions....90

7.2.1 VpSetLineState() 90
7.2.2 VpSetLineTone() 92
7.2.3 VpSetRelayState() 93
7.2.4 VpSetRelGain() 94
7.2.5 VpSendSignal() 95
7.2.6 VpSendCid() 96
7.2.7 VpContinueCid() 97
7.2.8 VpStartMeter32Q() 98
7.2.9 VpSetOption() 100
7.2.10 VpSetBFilter() 101
7.2.11 VpLineloAccess() 102
7.2.12 VpDeviceIoAccessExt() 103
7.2.13 VpLowLevelCmd16().... 104
7.2.14 VpGenTimerCtrl() 106

CHAPTER 8 STATUS AND QUERY FUNCTIONS ...... 107

8.1 Overview 107
8.2 Function Descriptions.... 108

8.2.1 VpGetEvent().... 108
8.2.2 VpGetLineStatus() 110
8.2.3 VpGetLoopCond() 111
8.2.4 VpGetOption() 112
8.2.5 VpGetLineState(). 113
8.2.6 VpFlushEvents() 113
8.2.7 VpGetResults() 114
8.2.8 VpClearResults() 115
8.2.9 VpGetDeviceStatusExt() 116
8.2.10 VpQuery() 117

CHAPTER 9 LINE TESTS 119

9.1 Overview 119

9.1.1 VpTestLine() 119
9.1.2 Test Types.... 120
9.1.3 Running Tests 120
9.1.4 Test Inputs.... 121
9.1.5 Test Outputs 121
9.1.6 Test Restrictions 122

9.2 Details of Test Primitives 123

9.2.1 VP_TEST_ID_PREPARE 123
9.2.2 VP_TEST_ID_CONCLUDE.... 123
9.2.3 VP_TEST_ID_SET_SENSE_GAIN_792 124
9.2.4 VP TEST ID OPEN VDC 125
9.2.5 VP_TEST_ID_OPEN_VAC 126
9.2.6 VP_TEST_ID_DIFF_VAC 127
9.2.7 VP_TEST_ID_IDC.... 128
9.2.8 VP_TEST_ID_DC_RLOOP 129
9.2.9 VP_TEST_ID_AC_RLOOP 130
9.2.10 VP_TEST_ID_HOOK_STATUS 131
9.2.11 VP_TEST_ID_ALT_REN.... 132
9.2.12 VP TEST ID 3ELE RES.... 133
9.2.13 VP TEST ID 3ELE CAP.... 134
9.2.14 VP_TEST_ID_KEYPAD 135
9.2.15 VP_TEST_ID_ARB_1TONE 137
9.2.16 VP_TEST_ID_DIALTONE.... 138
9.2.17 VP_TEST_ID_MONITOR_IV.... 139
9.2.18 VP_TEST_ID_3ELE_RES_VMID 140
9.2.19 VP TEST ID SET BATTERIES 141
9.2.20 VP_TEST_ID_GEN_TEST 142

CHAPTER 10 SYSTEM SERVICES.... 145

10.1 Overview 145
10.2 VP-API-II Reentrancy 145
10.3 Function Descriptions.... 146

10.3.1 VpSysEnterCritical() 146
10.3.2 VpSysExitCritical(). 147
10.3.3 VpSysDebugPrintf() 147

CHAPTER 11 HARDWARE ABSTRACTION LAYER.... 149

11.1 Overview 149
11.2 Function Descriptions.... 150

11.2.1 VpHalHbiInit() 150
11.2.2 VpHalHbiCmd() 150
11.2.3 VpHalHbiWrite() 151

11.2.4 VpHalHbiRead() 151

CHAPTER 12 INTERRUPT HANDLING.... 153

12.1 Overview 153
12.2 The Event Queue 153
12.3 Interrupt Pin Behavior.... 153
12.4 Handling Interrupts from VE792 Devices 154

CHAPTER 13 DEBUG FUNCTIONS 155

13.1 Overview 155
13.2 Types of Debug Output 155
13.3 Debug Output Selection at Compile Time 156
13.4 Debug Output Specificity 156
13.5 Debug Output Selection at Run Time.... 156
13.6 Portability Concerns 157
13.6.1 Static Variable Coherency.... 157
13.6.2 VpSysDebugPrintf() 157
13.6.3 ANSI X3.64 Colors 157
13.6.4 Displaying VpDeviceIdType and VpLineldType 158

APPENDIX A GLOSSARY.... 159

APPENDIX B FUNCTION INDEX.... 161

APPENDIX C RELAY CONFIGURATIONS.... 167

APPENDIX D REVISION HISTORY.... 169

Rev 17: 13-Sep-2010.... 169
Rev 18: 29-Oct-2010 169
Rev 19: 3-Dec-2010 169
Rev 21: 31-Mar-2011 169
Rev 22: 31-May-2011.... 169
Rev 24: 4-Nov-2011.... 169
Rev 25: 23-Dec-2011.... 169
Rev 26: 10-Feb-2012 169
Rev 27: 5-Apr-2012 169
Rev 28: 5-MAR-2013 169
Rev 29: 25-APR-2013 170
Rev 30: 20-JUNE-2014 170
Rev 31: February-2015 170
Rev 32: December-2015 170
Rev 33: JuLY-2016.... 170

1.1 ABOUT THIS USER'S GUIDE

This document describes the Microsemi VoicePath™ Application Program Interface, otherwise known as VP-API-II. It is used to control Microsemi's telephony Voice Termination Devices (VTDs). This chapter highlights the document structure and conventions and summarizes the VP-API-II architecture and features.

1.1.1 Chapter Overview

This user's guide consists of the following chapters:

Chapter 2, Profiles: Explains the concept of the VP-API-II profiles.

Chapter 3, System Configuration Functions: Describes the VP-API-II system configuration functions.

Chapter 4, Options: Describes the VP-API-II options.

Chapter 5. Events: Describes the VP-API-II events.

Chapter 6, Initialization Functions: Describes the VP-API-II initialization functions.

Chapter 7. Control Functions: Describes the VP-API-II control functions.

Chapter 8. Status and Query Functions: Describes the VP-API-II status and query functions.

Chapter 9, Line Tests Describes the VP-API-II line testing functions.

Chapter 10, System Services: Describes the VP-API-II system support functions.

Chapter 11. Hardware Abstraction Layer Describes the VP-API-II hardware abstraction layer functions.

Chapter 12, Interrupt Handling: Discusses methods for handling VP-API-II interrupts.

Chapter 13, Debug Functions: Describes debug capabilities of the VP-API-II.

Appendix A, Glossary: Defines uncommon terminology used throughout this document.

Appendix B, Function Index: Provides a summary of all VP-API-II functions.

Appendix C, Relay Configurations: Defines relay configurations for specified termination types.

Appendix D, Revision History: Revision history of this document.

1.1.2 Frequently Used Terms

The following terms are used extensively throughout this document:

Device: The term device refers to a Microsemi VTD. Examples of a device include Microsemi's conventional SLAC™ devices (CSLAC), Next-Generation SLAC devices (VE792), and Voice Control Processor (VCP) devices. The VP-API-II primarily configures and controls a device. A device provides services for one or more channels to perform functions of termination lines.

Channel: The term channel refers to resources associated with a device in performing the functions of a termination line. Thus, if a device has resources to support four termination lines, the device is said to have four channels.

Line: The term line means termination line in this document. Line refers to the complete system solution (application software, VP-API-II software, Microsemi VTDs, other hardware) that implements an FXS or FXO termination line. The line uses the channel resources of a device in order to realize the features of the line.

Refer to Appendix A, Glossary for the definition of other uncommon terms used in this document.

1.1.3 Documentation Conventions

The VP-API-II User's Guide uses the formatting conventions shown in Table 1-1.

Table 1-1 Documentation Conventions

Format Usage
Bold Courier New	Indicates a VP-API-II function or data type.
Plain Courier New	Indicates computer code or a file name.
Bold Blue Underlined Text	Indicates a hyper link cross-reference or a web site.
Italic	Emphasizes an important term.

1.2 VP-API-II OVERVIEW

The VP-API-II library is a C source code module that provides a standard software interface for controlling, testing, and passing digitized voice through a set of subscriber lines using Microsemi Voice Termination Devices. The VP-API-II hides the details of controlling Microsemi VTDs and allows software developers to focus on the application instead of the hardware.

1.2.1 Features

Listed below are some of the key features of the VP-API-II library. Note that some features depend on support from the underlying hardware.

• Provides an abstract, uniform software interface for any combination of Microsemi voice products.
• Provides a common way of organizing design-specific parameters using Profiles.
• Supports any combination of FXS and FXO lines configured for either loop-start signaling or ground-start signaling.
• Includes pulse-digit/flash decoder and ring/tone cadence engine.
• Can be used in any OS or non-OS environment.
• Fits into common driver and static/dynamic library models.
  • Supports various interrupt modes and both big-endian and little-endian microprocessors.
• Implemented in C code that is efficient, portable, and ANSI C compliant.

• Supports GR909 and GR844 type line testing (using additional Microsemi Line Test SW).

1.2.1.1 Profiles

Profiles are used by the VP-API-II to configure the device and line(s) to meet the customer specific requirement. They are C strings of 8-bit data generally corresponding to a series of device specific command+data sets. The goal of the VP-API-II is to allow an application to be written once for all Microsemi voice products with simple change only to the profiles. To simplify the generation of profiles, Microsemi provides a Windows based tool called Profile Wizard which allows encapsulation of all customer configuration needs within a single Profile Wizard project file.

The VP-API-II defines profiles for the following design parameters:

• Device Configuration
- AC transmission
- DC feed
- Ringing configuration
- Call-progress tones
- Cadence patterns
- Caller ID configuration
- Metering configuration

Note that the VP-API-II allows run-time change without device/line re-initialization of all parameters controlled by profiles except for those in the Device Profile (Device Configuration).

1.2.1.2 Options

Options are the set of device/line parameters that are generally changed during a normal call control application. As a consequence, all options can be changed during run-time without device or line re-initialization. The following is a short list of VP-API-II configuration options:

• Codec selection
  • PCM timeslot and highway assignment
• Pulse digit detection timing
  • Automatic state transition upon fault
• Loopback
• Battery selection
• Event masking

Please see Chapter 4, on page 29 for details about specific options.

1.2.2 Architecture

Figure 1–1 on page 4 illustrates a typical software block diagram of a system incorporating the VP-API-II. The VP-API-II module provides services to the Application Layer. The VP-API-II requires the System Services Layer and Hardware Abstraction Layer to operate correctly. This document describes the interfaces between the VP-API-II and those software modules implemented by the user. The following sections describe each of the blocks shown in Figure 1–1.

Figure 1-1 Software Block Diagram

graph TD
    A["Customer Application or Microsemi Demonstration Applications (QuickStart)"] --> B["Commercial OS, Custom OS, or non-OS System Software"]
    B <--> C["System Services (Software Interface Layer)"]
    C <--> D["VoicePath Application Program Interface II (VP-APHI)"]
    D <--> E["Hardware Abstraction Layer (HAL)"]
    E <--> F["Microsemi Voice Device Hardware"]
    G["VoicePath API-II Control\nPrimary application interface for Microsemi voice devices .\n- Initialize device\n- Handle events (interrupts )\n- Control line state\n- Set device options\n- Control tones and metering\n- Initiate line tests\n- Exchange voice packets"] --> D
    H["HAL Access\nAbstracts HBI and MPI device access.\n- Device read/write\n- HBI init and bootload\n- HBI command"] --> E
    I["System Services\nOS or Software Architecture Interface.\n- Interrupt control\n- Timer services\n- Enter/Exit critical"] --> C
    J["Global Voice Path"] --> D
    K["HBI / M PI"] --> E

1.2.2.1 VP-API-II

The VP-API-II is the core component of Microsemi's VoicePath Software Development Kit (SDK). This software module runs on the host microprocessor that controls one or more Microsemi VTDs. This code is supplied by Microsemi and should not require modification by the application developer.

1.2.2.2 Customer Application

This block represents the user's line management module that performs task such as initializing the system, configuring lines, changing line states in response to line events and other inputs, switching digitized voice traffic, etc. These functions may be distributed across a large and complex system, but they are shown as one block in Figure 1-1 for convenience. Microsemi provides example implementations of this layer as part of the VP-SDK.

1.2.2.3 Operating System

This block represents the operating system (if any) that the user is running on the host microprocessor. The VP-API-II does not directly utilize any operating system resources (e.g. queues, semaphores, etc.). However, the application developer may wish to use operating system features such as tasks or shared memory with the VP-API-II. Multi-Tasking Applications, on page 18 covers using the VP-API-II in a multitasking environment in detail. Note also that the System Services Layer may utilize operating system facilities depending on the application.

1.2.2.4 Hardware Abstraction Layer

The Hardware Abstraction Layer (HAL) provides access to Microsemi devices through the Host Bus or Microprocessor Interface (HBI or MPI) depending on the selected device. The HAL software is platform-dependent and must be implemented by the VP-API-II user. Microsemi provides example HAL source code with the VP-SDK. Refer to Hardware Abstraction Layer, on page 149 for further details.

1.2.2.5 System Services Layer

The System Services Layer abstracts platform-specific functions such as interrupt control and timing services. This layer derives the functions required by the VP-API-II from the facilities provided by the underlying hardware or operating system. This module is also platform-dependent and must be implemented by the VP-API-II user. Microsemi provides example System Services Layer source code with the VP-SDK. Refer to System Services, on page 145 for further details.

1.2.3 Supported Hardware Configurations

The VP-API-II supports many possible combinations of Microsemi devices. These hardware configurations are identified by a VpDeviceType and a termination type (VpTermType). Note that the VpDeviceType refers only to the device connected directly to the Host Processor.

The VP-API-II supports four broad classes of "Primary Device" types:

• Conventional SLAC

In this configuration the microprocessor running the VP-API-II is directly connected to one or more traditional Microsemi SLAC devices. The term CSLAC in this document refers to this hardware configuration. CSLAC devices control up to 8 lines and require host-provided timers.

– Details of CSLAC operation are covered in a separate document.

• Voice Control Processor (includes VCP and VCP2 device types)

In this configuration the microprocessor running the VP-API-II is directly connected to one or more Microsemi Voice Control Processor (VCP or VCP2) devices. VCP aggregates the control of several CSLAC devices, each controlling up to 8 lines. VCP2 aggregates the control of several CSLAC or VE792 devices. The number of SLAC devices that can be controlled by a single VCP or VCP2 depends on the SLAC type and VCP firmware capabilities. VCP devices do not require host-provided timers.

– Details of VCP operation are covered in a separate document.

- VE792 chipset (also called "792 stand-alone")

In this configuration the microprocessor running the VP-API-II is directly connected to one Microsemi's VE792 (SLAC) chipset. A single VE792 chipset controls up to 8 lines and does not require host-provided timers.

• Metallic Line Testing (MeLT)

In one version of this configuration (MeLT-792), the microprocessor running the VP-API-II is directly connected to a Microsemi SLAC (Le79258) device. The VP-API-II contains special MeLT software that supports line testing, but does not support normal POTS call control functionality. The VP-API-II controls a single SLAC device and multiple drivers.

In another version of this configuration (MeLT-VCP), the microprocessor running the VP-API-II is directly connected to a Microsemi Voice Control Processor (Le79128) device. The VCP contains special MeLT firmware that supports line testing, but does not support normal POTS call control functionality. The VCP controls a single SLAC (Le79258) device and multiple drivers.

In both versions, the VCP or SLAC devices do not require host-provided timers.

– Details of MeLT operation are covered in a separate document.

The combinations of features, terminations, and devices described in this document are shown in Table 1-2 on page 6. The Primary Device column indicates which type of device the host microprocessor is directly interfaced to. The Software Device Type column indicates which

VpDeviceType constant maps to each Primary Device. The Part Numbers column indicates which Microsemi parts or device families apply to each configuration. The Configuration Name column lists the terminology used throughout this document to refer to a specific device configuration.

Table 1-2 Supported Device Configurations

Primary Device	Software Device Type (VpDeviceType)	Part Numbers Configuration Names
VE792	VP_DEV_792_SERIES	Le79238	VE792VE792-NT (No Test)VE792-BT (Basic Test)

Some VP-API-II features are only supported with certain device configurations. This document refers to the specific device Configuration Names shown in Table 1-2 when referring to such a device-specific feature.

Each of the device configurations described above supports one or more of the line termination types listed in Table 1–3.

Table 1-3 Supported Termination Types

Software Termination Type(VpTermType)	Devices Description
VP_TERM_FXS_GENERIC	All Generic FXS termination
VP_TERM_FXS_RR	VCP-790,VCP2-790,VCP2-792VE792	SLIC Le792x2/Le79271 with shared ringing, reset relay and with test load
VP_TERM_FXS_TI	VCP2-792VE792	SLIC Le79271 with test-in relay and test load.
VP_TERM_FXS_RR_TI	VCP2-792VE792	SLIC Le79271 with ringing/reset relay and test-in bus
VP_TERM_FXS_RR_MW	VCP2-792VE792	SLIC Le79271 with ringing/reset relay, and message-waiting lamp relay

1.2.3.1 VE792 Chipset

The system architecture for VE792 Chipset products is shown below.

Figure 1-2 VoicePath System Architecture Example Using VE792 Devices

graph TD
    A["HOST"] --> B["Application"]
    B --> C["SLAC Control"]
    B --> D["VE792 SLAC #0"]
    B --> E["..."]
    B --> F["VE792 SLAC #(N-1)"]
    D --> G["FXS Termination #0"]
    D --> H["..."]
    E --> I["FXS Termination #(M-1)"]
    F --> J["FXS Termination #(N-1)M"]
    F --> K["..."]
    F --> L["FXS Termination #NM - 1"]
    style A fill:#f9f,stroke:#333
    style B fill:#ccf,stroke:#333
    style C fill:#cfc,stroke:#333
    style D fill:#fcc,stroke:#333
    style E fill:#fcc,stroke:#333
    style F fill:#fcc,stroke:#333
    style G fill:#fff,stroke:#333
    style H fill:#fff,stroke:#333
    style I fill:#fff,stroke:#333
    style J fill:#fff,stroke:#333
    style K fill:#fff,stroke:#333
    style L fill:#fff,stroke:#333

In a VE792 architecture, the VP-API supports one or more VE792 SLAC devices connected to and controlled by a host processor that uses one or more (serial) HBI interfaces. Each line derived from the SLAC device can be configured for one of the FXS termination types in Table 1–3, provided supporting circuitry is available.

1.2.4 VP-API-II Function Summary

This section provides a brief overview of each of the VP-API-II functions.

1.2.4.1 System Configuration

The VP-API-II uses the concept of device objects and line objects to manage run-time support for different types of VTDs and line terminations. An instance of a device object represents a physical VTD controlled by the VP-API-II. A device object can represent any type of VTD as long as support for that type of VTD is included in the VP-API-II at compile-time.

Device contexts are essentially handles to device objects. There must be exactly one instance of a device object per VTD in the system. There is normally one device context for each device object, but in some multitasking systems there can be many device contexts referring to a single device object.

Similarly, an instance of a line object represents one physical line managed by the VP-API-II. Line contexts are basically handles to line objects. There must be exactly one instance of a line object per physical line in the system. There is normally one line context for each line object, but in some multitasking systems there can be many line contexts referring to a single line object.

The System Configuration functions manage device objects, line objects, device contexts, and line contexts.

• VpMakeDeviceObject() – Initializes a device object to control a physical device. Also initializes a device context that refers to the new device object.
• VpMakeLineObject() – Initializes a line object and associates it with a device object. Also initializes a line context that refers to the new line object.
• VpMakeDeviceCtx() – Allows creating more than one device context referring to the same device object, which is useful in multitasking applications.
• VpMakeLineCtx() – Allows creating more than one line context referring to the same line object, which is useful in multitasking applications.
• VpFreeLineCtx() – Tells the API that the application no longer needs a particular line context.
• VpGetDeviceInfo() – Retrieves device-specific information from a device or line context.
• VpGetLineInfo() – Retrieves line-specific information from a device or line context.
• VpMapLineId() – Allows application mapping of generic "line id" to the line.

1.2.4.2 Initialization

These functions initialize aspects of the system or perform the configuration required before a particular feature can be used.

• VpInitDevice() – Initializes all lines of a device and applies the specified profiles to those lines.
• VpInitLine() – Initializes an individual FXS line and applies the specified profiles to that line.
• VpConfigLine() – Sets the AC, DC, and Ringing Profiles for an individual line.
• VpCalCodec() – Calibrates internal SLAC level parameters.
• VpCalLine() - Calibrates internal line level parameters.
• VpInitRing() – Sets the ringing parameters such as the ringing cadence and Caller ID

profile for an individual line.

• VpInitCid() – Prepares a line for a Caller ID ring sequence.
• VpInitMeter() – Configures the metering signal generator of an individual line.
• VpInitProfile() – Initializes the device's profile tables.

- VpSetBatteries() – Sets the battery settings in the device, used to improve dc feed performance on devices that support this function.

1.2.4.3 Control

The control functions manage the current line state and set options that may change during run-time.

• VpSetLineState() - Sets a line to the requested state.
• VpSetLineTone() – Generates a cadenced tone on a line.
• VpSetRelayState() - Sets the line relay configuration.
• VpSetRelGain() – Sets the relative transmit or receive gain for a line.
• VpSendSignal() – Generates message waiting pulse on FXS lines, or pulse and DTMF digits on FXO lines.
• VpSendCid() – Starts a Caller ID sequence on a FXS line without waiting for a ring state change.
• VpContinueCid() – Refreshes the Caller ID buffer for a FXS line during message transmission.
• VpStartMeter32Q() - Starts metering on an FXS line.
• VpSetOption() – Sets various device and line specific options.
• VpSetBFilter() – Enables with the coefficients provided or disables the B-Filter.
• VpLineIoAccess() – Controls input/output pins for a specific line.
• VpDeviceIoAccessExt() – Controls device input/output pins. An extended replacement for VpDeviceIoAccess().
• VpLowLevelCmd16 () – Allows the application to issue low level commands to the 792 series SLAC. This function is an internal debugging tool that should not be used by the application.
• VpGenTimerCtrl() - Provides control of the SLAC built-in general purpose timers.

1.2.4.4 Query/Status

These functions get information and events from the VTD.

• VpGetEvent() – Returns events corresponding to a device.
• VpGetLineStatus() – Returns the state of a particular status flag for one line.
• VpGetLoopCond() – Reads loop conditions for a line and returns parameters such as voltage, current, and resistance.
• VpGetOption() – Returns the current setting of an option.
• VpGetLineState() – Reads the current line state.
• VpFlushEvents() - Flushes all outstanding events.
• VpGetResults() – Reads the data associated with an event.
• VpClearResults() – Discards the data associated with an event.
• VpGetDeviceStatusExt() – Returns the state of a particular status flag for all lines of a device.

1.2.4.5 Line Testing

The VP-API-II provides advanced line testing capabilities which are utilized by the VoicePath Test Library.

• VpTestLine() – This is the common entry point for all VP-API-II line tests, including:
• Loop voltage, current, and resistance measurement.
  – Tone measurement, tone generation.
• Noise and hybrid loss measurement.
• Keypad (DTMF and pulse-digit) test.
  – SNR and quantization distortion measurement.

1.2.4.6 System Services Layer

The System Services Layer (SSL) functions are platform-specific and must be implemented for the target host processor.

• VpSysEnterCritical() – Blocks entry into a critical section of VP-API code through some user-defined method.
• VpSysExitCritical() – Marks the end of a VP-API critical code section.
• VpSysDebugPrintf() – Print mechanism used by VP-API-II Debug features.

1.2.4.7 Hardware Abstraction Layer

The Hardware Abstraction Layer (HAL) functions contain the lowest level of code used to directly interface with the VTDs. These functions are platform-specific and must be implemented for the target host processor.

• VpHalHbiInit() – Performs platform-specific initialization of the HBI.
• VpHalHbiCmd() - Issues an HBI command.
• VpHalHbiWrite() - Performs HBI write transactions.
• VpHalHbiRead() – Performs HBI read transactions.

1.2.5 Basic VP-API-II Data Types

Table 1-4 lists the basic data types used extensively throughout the VP-API-II. These types are defined in the vp_api_types.h header file and must be reviewed/modified by the customer to verify that the definitions are correct on the target platform. Many other types are defined within the VP-API-II, but the user should never redefine any VP-API-II types other than those in vp_api_types.h.

Table 1-4 Basic VP-API-II Data Types

Type Description
VpDeviceIdType Application-dependent device ID, user defined type.
VpLineIdType Application-dependent line ID, user defined type.
bool	Boolean variable assigned TRUE (1) or FALSE (0).
uint8 8-bit unsigned integer.
uint16 16-bit unsigned integer.
uint32 32-bit unsigned integer.
int8 8-bit signed integer.
int16 16-bit signed integer.
int32 32-bit signed integer.
uint8p Pointer to 8-bit unsigned integer.
uint16p Pointer to 16-bit unsigned integer.
uint32p Pointer to 32-bit unsigned integer.
int8p Pointer to 8-bit signed integer.
int16p Pointer to 16-bit signed integer.
int32p Pointer to 32-bit signed integer.
VpProfilePtrType Pointer to profile data.
VpVectorPtrType Pointer to line testing raw sample buffer.

1.2.6 VP-API-II Function Return Type

The vast majority of VP-API-II functions return a result code indicating whether the function executed successfully, and if not, what type of error occurred. The enumeration type VpStatusType is defined for this purpose. All VpStatusType codes are listed in the table below.

Table 1-5 VP-API-II Result Codes

Type Description
VP_STATUS_SUCCESS Function executed successfully.
VP_STATUS_FAILURE Function execution failed due to unspecified error.
VP_STATUS_FUNC_NOT_SUPPORTED Function not supported for the device.
VP_STATUS_INVALID_ARG	One or more arguments to the function are invalid. No command is issued to the VTD.
VP_STATUS_MAILBOX_BUSY	Function failed because the device's downstream mailbox is busy. The application should try the same call again later. The VP-API-II can be configured to repeatedly try the mailbox, which should hide most of these errors. See vp_api_cfg.h.
VP_STATUS_ERR_VTD_CODE	Unsupported device type or termination type requested in call to VpMakeDeviceObject(), VpMakeLineObject(), VpMakeDeviceCtx(), or VpMakeLineCtx().
VP_STATUS_OPTION_NOT_SUPPORTED	Unsupported option requested in call to VpSetOption() or VpGetOption().
VP_STATUS_DEVICE_BUSY	Resources required to perform the requested function are not available.
VP_STATUS_MAILBOX_EMPTY	Returned by VpGetResults() if there is no data in the upstream mailbox.
VP_STATUS_ERR_MAILBOX_DATA	Returned by VpGetResults() if the data in the upstream mailbox does not match the expected data type.
VP_STATUS_ERR_HBI HBI communication with the device failed.
VP_STATUS_DEV_NOT_INITIALIZED	The specified device object is not yet initialized via VpInitDevice().
VP_STATUS_ERR_PROFILE	VP-API-II detected an error in the format of a profile. This error is also returned if the application attempts to use an uninitialized profile from the profile table.
VP_STATUS_DEDICATED_PINS	Can be returned when Application is trying to configure or write to I/O pins that are dedicated to the termination type. When this error returns, all pins NOT dedicated to the termination type will be changed. Pins that are dedicated will be unchanged.
VP_STATUS_INVALID_LINE	VP-API-II detected that the physical line corresponding to the line context does not exist.
VP_STATUS_LINE_NOT_CONFIG	The requested operation requires that the line first be configured with an AC, DC, and/or Ringing Profile.

1.3 API-II SOURCE VERSION NUMBER

Due to feature (device, termination, or function) additions and bug fixes, an application may at runtime want to determine the current version of the VP-API-II release. This can be found in the header file "vp_api.h" from the macro:

define VP_API_VERSION_TAG (0xZZYYRR)

Where ZZ is a hex value corresponding to the Major Number, YY is a hex value corresponding to the Minor Number, and RR is a hex value corresponding to the Revision Number. Definitions of Major, Minor, and Revision Number are:

• Major Number : Indicates a complete interface change such that the application is not likely to

compile, and will not work. An application detecting a Major release number change should immediately stop. Major number = 02 will cover the entire API-II series.

• Minor Number: Indicates a functional change or addition. A new device, termination type, function, event, or option would justify a new Minor number. This will occur at times, but should not break a well written application (in particular, one that uses proper default handling and unmasks only those events the application is designed to handle).
• Revision Number: Used for bug fixes only. Functional compatibility is guaranteed, although code that relies upon the erroneous behavior may be broken.

1.4 APPLICATION NOTES

The VP-API-II is designed to allow a single application to use any Microsemi device, assuming the application takes into account the differences in device capabilities (noted in this document). Every VP-API-II function and option may be used for every device and line type. In cases where a function or option is not supported, the function will return VP_STATUS_FUNC_NOT_SUPPORTED or VP_STATUS_OPTION_NOT_SUPPORTED, and the device/line will not be affected.

While each application will have its own set of requirements (when device and line initialization will occur, when to configure ringing parameters, multi-single threaded application, etc.) the following basic steps should be followed for all applications:

1. VpMakeDeviceObject()
2. VpMakeLineObject() /* Repeat for each line associated with the device */
3. VpInitDevice()
4. Wait for Init Device complete event (VP_DEV_EVID_DEV_INIT_CMP)
5. (optional) Check for FEMF or Hazardous Potential on the line. This requires use of the VoicePath Test Library.
6. Set relay state to VP_RELAY_NORMAL.
7. Set all channels to the idle state (generally VP_LINE_STANDBY or VP_LINE_OHT).
8. Proceed with normal configuration and call control.

1.5 TECHNICAL SUPPORT

For technical support, logon to the issue tracker in the Microsemi Software Delivery System (SDS) at the following URL: http://sds.zarlink.com/software.php

2.1 OVERVIEW

Profiles are structures that contain design data to meet specific system requirements. Many VP-API-II functions take profiles as one or more arguments. There are several different types of profiles. Each defines a different set of parameters for a service aspect of the device. Table 2–1 provides a summary of all the profiles that can be used by the VP-API-II. Some profile types are not utilized by certain device types. Also, the content of some profiles may vary according to the device type.

2.2 PROFILE TYPES

Table 2-1 VP-API-II Profile Types

Profile Type Description
Device Profile	Contains the default start-up values for device-specific configuration options that are normally set at initialization and never changed.
AC Profile	Used for programming the transmission characteristics of the system, the AC Profile holds the VTD programmable gain and filter coefficients and data. Each AC Profile is designed to address the specific AC transmission requirements of a given design.
DC Profile	Holds the VTD DC feed commands and data. Each DC Profile is designed to address the specific DC feed requirements of a given design. Also contains the threshold values for various fault detectors.
Ringing Profile	Contains the commands and data to set up the ringing signal generator of the VTD. Different profiles can be used to vary the ringing characteristics of a line. Options available in the Ringing Profile include ringing waveform, frequency, amplitude, and DC offset.
Metering Profile	Contains the commands and data to set up the metering pulse signal generator of the VTD. The parameters configured include pulse current limits, voltage limits, and frequency.
Tone Profile	Defines the various call progress tones that might be used in a system. Examples tones include: dial tone, busy, ring-back, and reorder.
Ringing Cadence Profile	Defines the various cadences that might be used when ringing a phone.
Tone Cadence Profile	Defines the various cadences that might be used when generating call progress tones.
Caller ID Profile	Defines the off-hook and on-hook signaling protocol for services such as Caller ID and message waiting indication.

All profiles should be generated by the Microsemi Profile Wizard, but in some cases run-time modification may be necessary. In such cases, care must be taken to ensure that the resulting profiles are compliant with the relevant Profile Wizard specification, available from Microsemi Technical Support.

2.3 PROFILE TABLES

The VP-API-II provides profile tables that allow one or more instances of each type of profile to pre-loaded into the system and accessed during normal operation by an index rather than pointer. Figure 2-1 illustrates the concept of profile tables.

Figure 2-1 Profile Tables

graph LR
    A["Device Profile"] --> B["AC Profile"]
    B --> C["DC Profile"]
    C --> D["Ringing Profile"]
    D --> E["Ringing Cadence Profile"]
    E --> F["Tone Profile"]
    F --> G["Metering Profile"]
    G --> H["Caller ID Profile"]
    H --> I["Tone Cadence Profile"]

Each box in Figure 2-1 represents one instance of a profile. Each stack of boxes represents a table of that specific type of profile. In this example the number and type of profiles shown applies to the VCP device. The application refers to an individual profile within a profile table by passing a profile table index into VP-API-II functions. Profile table indices are simply C macros in the form of VP_PTABLE_INDEX (n) where 1 ≤ n ≤ 15 . VP_PTABLE_NULL is a special value indicating that no profile argument is specified.

The application can load data into a profile table entry at any time. However, overwriting a profile table entry while that profile is in use could result in unusual behavior. Profiles are typically loaded by the application during VTD initialization. When the host application requires the services of the profile, it simply refers to the profile by its index in the profile table. For example, the application can call VpInitProfile() to load a ringing cadence profile into the profile table. In subsequent calls to VpInitRing(), the application can apply this ringing cadence to a line by specifying the profile's index in the profile table in the call to VpInitRing(). If the application modifies this ringing cadence profile entry by calling VpInitProfile() again, it should force the VTD to apply the new profile to the lines using the modified profile entry by calling VpInitRing() again for each line.

Alternatively, the application can bypass the profile tables and load profiles directly into the device by passing a pointer to a profile instead of a profile table index. Any VP-API-II function profile argument that is not a valid profile table index is automatically interpreted as a pointer to a profile in memory. When a profile is passed by reference, the VP-API-II copies the profile into a temporary variable or directly into the VTD, so the application can delete its copy of the profile after the VP-API-II function returns.

Table 2-2 lists the number and type of profiles supported for the VE792 device family. Note that for VE792 devices, the Profile Table layout can be altered at compile time according to customer preferences, with the aid of Microsemi Technical Support.

Table 2-2 Profile Table Capacity

Profile Type Number	of Profiles
Device Profile 1
AC Profile 2
DC Profile 2
Ringing Profile 2
Ringing Cadence Profile 4
Tone Profile 10
Metering Profile 2
Caller ID Profile 2
Tone Cadence Profile 11

2.4 PROFILE FUNCTIONS

Below is a list of the VP-API-II functions that use profiles. Please refer to the appropriate function descriptions for more information about these functions.

• VpInitProfile() , on page 87
• VpInitDevice(), on page 77
- VpInitLine(). on page 79
- VpConfigLine(). on page 80
• VpInitRing(), on page 83
• VpInitMeter(), on page 86
- VpSetLineTone(). on page 92
• VpSendCid(). on page 96
- VpSetBFilter(), on page 101

3 SYSTEM CONFIGURATION FUNCTIONS

3.1 OVERVIEW

The VP-API-II supports the following key features:

• A single host microprocessor can control multiple device types and multiple line termination types through a common API.
  • The VP-API-II is compatible with both multi-tasking and single-threaded operating systems.

To provide the key features, the VP-API-II introduces the concept of device objects, line objects, device contexts and line contexts. The System Configuration functions described in this chapter manage these objects and contexts, and are summarized below.

• VpMakeDeviceObject() – Initializes a device object to control a physical device. Also initializes a device context that refers to the new device object.
• VpMakeLineObject() – Initializes a line object and associates it with a device object. Also initializes a line context that refers to the new line object.
• VpMakeDeviceCtx() – Allows creating more than one device context referring to the same device object, which is useful in multitasking applications.
• VpMakeLineCtx() – Allows creating more than one line context referring to the same line object, which is useful in multitasking applications.
• VpFreeLineCtx() – Tells the API that the application no longer needs a particular line context.
• VpGetDeviceInfo() – Retrieves device-specific information from a device or line context.
• VpGetLineInfo() – Retrieves line-specific information from a device or line context.
• VpMapLineWidth() – Allows application mapping of generic "line id" to the line.

3.2 OBJECTS AND CONTEXTS

The VP-API-II itself does not contain any static data related to any line or device. All of the necessary information is stored in device and line object instances, which are indirectly passed to VP-API-II functions via device and line contexts. There is exactly one device object for every VTD in the system, and there is exactly one line object for every line controlled by each VTD. The actual content of the device and line objects varies depending on the type of VTD(s) used in the system.

Device and line contexts are essentially generic "handles" to device and line objects, respectively. An instance of the device context can refer to any type of valid device object. Similarly, an instance of a line context can refer to any type of valid line object. The purpose of the device/line contexts is to hide the specific type of the underlying device/line objects from the top-level VP-API-II functions. This allows the application to remain the same regardless of the specific device or line (within the supported functionality of the device/line type).

(More than one device context can refer to a single device object. Similarly, more than one line context can refer to a single line object. This would only occur in a shared memory scenario in which the line/device objects have different addresses in different processes.)

Figure 3–1 illustrates the interconnections between these objects and contexts in the simplest case, where the VP-API-II is controlling one primary device that supports N lines. In this example there is only one context associated with each object. The generic device context contains a link (pointer)

to the device-specific device object, and it also contains a link to each line context associated with the device. Each generic line context contains a link to a device-specific line object and a link back to its parent device context. Note that Figure 3-1 does not precisely depict the actual C implementation of the device context, device object, line context, and line object structures.

Figure 3-1 Device and Line Objects and Contexts

graph TD
    A["Device Context"] --> B["Device Object"]
    A --> C["Line Context"]
    C --> D["Line Object"]
    A --> E["Line Context"]
    E --> F["Line Object"]
    A --> G["Line Context"]
    G --> H["Line Object"]
    A --> I["Line Context"]
    I --> J["Line Object"]
    A --> K["Line Context"]
    K --> L["Line Object"]

As stated above, the VP-API-II does not allocate any storage for any type of object or context. Therefore, the application must allocate storage for these structures, then execute VP-API-II functions to initialize the device and line objects and their respective contexts. It is critical that the application avoid freeing or overwriting the memory space allocated for any object or context until the services of the associated device or line are no longer needed. The contents of the device/line objects and contexts are managed by the VP-API-II and should never be modified by the application. The application should avoid directly accessing the device/line objects and contexts. The VP-API-II provides functions such as VpGetDeviceInfo() and VpGetLineInfo() that allow the application to get information for the device and line, respectively.

The following table shows device and line object types that are associated with each device family supported by the VP-API-II. Note that appropriate compile-time switches must be set to include the source code defining the desired device and line object types. These conditional flags are defined in the vp_api_cfg.h file.

Table 3-1 Device and Line Objects

VpDeviceType Compile-Time Switch Device Object Line Object
VP_DEV_792_SERIES VP_CC_792_SERIES Vp792DeviceObjectType Vp792LineObjectType

3.3 MULTI-TASKING APPLICATIONS

It may be desirable to have multiple tasks controlling various aspects of the system. For example, one process may handle call control, while another management process needs to query line status or perform line testing. In this example, both tasks must share access to the VP-API-II.

Implementations containing multiple tasks that utilize the VP-API-II have additional requirements and constraints. This section describes aspects of the VP-API-II designed to handle this special

case. This section does not apply to implementations not employing multiple tasks using the VP-API-II.

Recall that the device and line objects contain state information pertaining to the associated device or line. There must be exactly one device object for each VTD in the system and exactly one line object for each line in the system, regardless of the number of tasks. However, if the tasks do not share a common address space, each task needs its own context for each line and device it controls.

Figure 3-2 Multi-Tasking Example

Diagram illustrating the connection between FXS/FXO Termination devices, CSLAC device, and Line Object components, with annotations on device count and line context.

By default, the VpMakeDeviceObject() and VpMakeLineObject() functions create the object and one context associated with the new object. When the VP-API-II is employed by multiple tasks, one task is responsible for creating the necessary line and device objects. All tasks that use the VP-API-II can create contexts and associate them with the single object instance using VpMakeDeviceCtx() and VpMakeLineCtx() described later in this section. Thus, each task's contexts are unique handles to global objects.

Note that only one task should call VpGetEvent() and VpGetResults(). If multiple tasks need to receive VP-API-II events, a centralized event dispatcher task should be implemented to call VpGetEvent() and VpGetResults() and forward the events to the desired tasks.

3.3.1 Multi-Tasking with Protected Memory

In multi-tasking environments with memory protection, a shared memory region is necessary to share the device and line objects between many processes. In the example depicted in Figure 3-3. on page 20, a shared memory region is shown with two tasks (A and B) both needing access to the VP-API-II. One process is responsible for creating the shared memory region, and creating the desired device and line objects using VpMakeDeviceObject() and VpMakeLineObject().

If the shared memory has a different address in each process, then each process must create its own device and line contexts using VpMakeDeviceCtx() and VpMakeLineCtx(). If the shared

memory has the same address in each process, then the contexts can be placed in the shared memory segment, and these function calls are unnecessary.

If all processes share a common address space, then the API can store profile pointers in the line/device objects. This saves memory vs. copying the profiles into the objects. To enable this behavior, #define VP_COMMON_ADDRESS_SPACE in vp_api_cfg.h.

Figure 3-3 Protected Memory Example

graph TD
    A["Profile Table (Optional)"] --> B["Line Object 1"]
    A --> C["Line Object 2"]
    A --> D["Line Object 3"]
    A --> E["Line Object 4"]
    A --> F["Device Object"]
    G["Shared Memory Region"] --> H["Line Context 1"]
    G --> I["Line Context 2"]
    G --> J["Line Context 3"]
    G --> K["Line Context 4"]
    G --> L["Device Context"]
    M["Task A (Local Memory)"] --> N["Line Context 1"]
    M --> O["Line Context 2"]
    M --> P["Line Context 3"]
    M --> Q["Line Context 4"]
    M --> R["Device Context"]
    S["Task B (Local Memory)"] --> T["Line Context 1"]
    S --> U["Line Context 2"]
    S --> V["Line Context 3"]
    S --> W["Line Context 4"]
    S --> X["Device Context"]
    H --> Y["Line Context 1"]
    H --> Z["Line Context 2"]
    H --> AA["Line Context 3"]
    H --> AB["Line Context 4"]
    H --> AC["Device Context"]

3.4 FUNCTION DESCRIPTIONS

3.4.1 VpMakeDeviceObject()

SYNTAX vpStatusType

VpMakeDeviceObject(

VpDeviceType deviceType, /* Type of Device (or device object) */

VpDeviceIdType deviceId, /* Device chip select identity */

VpDevCtxType *pDevCtx, /* Pointer to the Device Context */

void *pDevObj) /* Pointer to the Device Object */

DESCRIPTION

This function creates a device object and device context in memory allocated by the application. It uses the argument deviceId to identify the chip select when communicating with the device. The deviceType argument selects the type of device and may be any of the VpDeviceType values defined in Table 3-1. This function takes a pointer to a device context (pDevCtx) and a pointer to a device object (pDevObj), both of which must point to memory allocated for these structures. VpMakeDeviceObject() returns VP_STATUS_INVALID_ARG if pDevCtx or pDevObj is VP_NULL. Otherwise, both the device context and device object are initialized with appropriate values based on the device type. The device context can be passed to other VP-API-II functions after it is initialized by this function.

Notes:

1. If this function does not return VP_STATUS_SUCCESS, then the application must not use the device context created here for any other -API-II calls.
2. No other VP-API-II functions should be called before invoking this function.
3. The type of the device object allocated by the application must match with deviceType. The VP-API-II has no way to check this condition, and memory buffer overrun could occur if there is a mismatch.
4. The VP-API-II will not know if more than one device object is created to refer to the same physical device. This scenario could cause unpredictable results. See VpMakeDeviceCtx(), on page 23 for details on creating more than one device context referring to the same device object.
5. The definition of VpDeviceIdType may be modified as required by the application. The VP-API-II itself does not interpret deviceId, but simply passes deviceId to the HAL functions (Chapter 11) when attempting to access the physical device associated with this device object.

RETURNS

See VP-API-II Function Return Type, on page 10

EVENTS

GENERATED

None

DEVICES All

TERMINATIONS All

3.4.2 VpMakeLineObject()

SYNTAX vpStatusType

VpMakeLineObject(

VpTermType termType, /* Type of line termination */

uint8 channelId, /* Numeric ID for this channel */

VpLineCtxType *pLineCtx, /* Pointer to the Line Context */

void *pLineObj, /* Pointer to the Line Object */

VpDevCtxType *pDevCtx) /* Ptr to associated device context */

DESCRIPTION

This function initializes a line object and line context in memory allocated by the application. The termination type parameter (termType) describes the circuitry associated with the termination. The termination types matched to the devices that support each type are defined in Table 1–3.

This function associates the specified channelId with the supplied Line Object. The channelIds for VE792 SLACs are numbered 0 to 7.

While most interactions between the host software and the API will use the *pLineCtx pointer, it may be convenient to map a customer-defined channel identifier ("lineId") to each line. In this case, the application may use the VpMap所在地() function to associate a latitude value to each channel. This allows the host controller identify the channels in any convenient way. For line-specific events, the VpGetEvent() function will set the latitude, channelID, and pLineCtx members in the event structure for line or channel identification, as preferred by the application.

This function should be called once and only once for each channel managed by each VTD.

This function returns VP_STATUS_INVALID_ARG if pLineCtx or pLineObj is VP_NULL. Otherwise, both the line context and line object are initialized with appropriate values based on the device type indicated by the device context (pDevCtx) argument. The line context can be passed to other VP-API-II functions after it is initialized by this function.

Notes:

1. No line-specific VP-API-II functions should be called before invoking this function.
2. The device context pointed to by pDevCtx must be initialized with VpMakeDeviceObject() or VpMakeDeviceCtx() before calling this function.
3. The type of line object allocated by the application must be compatible with the device type of the given device context. The VP-API-II has no way to check this condition, and the application could fail if there is a mismatch. See Table 3-1 for a list of device types and matching line object types.
4. This function must be called before executing VpInitDevice(). See VpInitDevice(), on page 77 for more information.
5. The VP-API-II will not know if more than one line object is created to refer to the same physical line. This scenario could cause unpredictable results. See VpMakeLineCtx(), on page 24 for more details on creating more than one line context referring to the same line object.

FUNCTION RETURNS

See VP-API-II Function Return Type, on page 10

EVENTS GENERATED

None

DEVICES All

TERMINATIONS All

3.4.3 VpMakeDeviceCtx()

SYNTAX vpStatusType

VpMakeDeviceCtx(

VpDeviceType deviceType, /* Type of device (or device object) */

VpDevCtxType *pDevCtx, /* Pointer to the device context */

void *pDevObj) /* Pointer to the device object */

DESCRIPTION

This function associates a device object with a device context and initializes the device context. It is useful in multitasking applications where more than one process accesses a single device.

Only one process should initialize the device object by calling VpMakeDeviceObject(). It is possible to initialize a device object without initializing a device context by calling the VpMakeDeviceObject() function with VP_NULL for the pDevCtx argument.

Subsequently, any process that wants to refer to the same device object could call this function to create a device context that can be used with other VP-API-II functions. The deviceType argument must indicate the device type that was specified during the device object creation. The pDevObj argument must point to the same device object that was used during its creation.

This function is only needed in multi-threaded applications, in which each process has its own address space.

This function associates a device object with a device context and initializes the device context. The device object data is unaffected by this function which is assumed to have been properly created/ initialized by calling VpMakeDeviceObject() by a "master" thread. Any process that wants to refer to the same device object initialized by the "master" thread must call this function with a pointer to the shared device object data (pDevObj argument).

The deviceType argument must indicate the device type that was specified during the device object creation.

The pDevCtx argument must contain a pointer to the device context that needs to be initialized.

After calling this function (if return == VP_STATUS_SUCCESS), the calling thread can then pass the device context pointer (pDevCtx) to other VP-API-II functions.

Notes:

1. The process of creating new device contexts does not affect any state information that is stored in the device object or the device itself.

RETURNS

See VP-API-II Function Return Type, on page 10

EVENTS

GENERATED

None

DEVICES All

TERMINATIONS All

3.4.4 VpMakeLineCtx()

SYNTAX vpStatusType

VpMakeLineCtx(

VpLineCtxType *pLineCtx, /* Pointer to the line context */

void *pLineObj, /* Pointer to the line object */

VpDevCtxType *pDevCtx) /* Ptr to associated device context */

DESCRIPTION

This function is only needed in multi-threaded applications, in which each process has its own address space.

This function associates a line context with a device context and line object, and initializes the line context. The line object data is unaffected by this function which is assumed to have been properly created/initialized by calling VpMakeLineObject() by a "master" thread. Any process that wants to refer to the same line object initialized by the "master" thread must call this function with a pointer to the shared line object data (pLineObj argument).

The pLineCtx argument must contain a pointer to the line context that needs to be initialized.

The pLineObj argument must contain a pointer to the (shared memory) line object that needs to be associated with the line context pointed to by pLineCtx.

The pDevCtx argument must contain a pointer to the device context that needs to be associated with the line context pointed to by pLineCtx.

After calling this function (if return == VP_STATUS_SUCCESS), the calling thread can then pass the line context pointer (pLineCtx) to other VP-API-II functions.

Notes:

The process of creating new line contexts does not affect any state information that is stored in the line object or the device itself.

RETURNS

See VP-API-II Function Return Type, on page 10

EVENTS GENERATED

None

DEVICES All

TERMINATIONS All

3.4.5 VpFreeLineCtx()

SYNTAX vpStatusType

VpFreeLineCtx(

VpLineCtxType *pLineCtx) /* Pointer to line context */

DESCRIPTION

This function removes the association between a device context and a line context previously made when calling VpMakeLineObject() or VpMakeLineCtx(). Calling this function tells the VP-API-Ⅱ that the application no longer requires services from the line associated with pLineCtx and would like to reclaim the memory allocated. Similarly, if the application reallocates the memory for the line context then it MUST call this function in order to avoid memory access violations and segmentation faults.

In multi-threaded applications, this function must be called for all such line contexts to completely remove all pointers to the (shared) line object. See Multi-Tasking Applications, on page 18 for details.

Notes:

This function does not alter the state of the physical line. The application must perform any required cleanup tasks, such as placing the line in Disconnect mode and disabling the interrupts for the line before calling this function.

RETURNS

See VP-API-II Function Return Type, on page 10

EVENTS GENERATED

None

DEVICES All

TERMINATIONS All

3.4.6 VpGetDeviceInfo()

SYNTAX vpStatusType

VpGetDeviceInfo(
    VpDeviceInfoType    /* Pointer to device info */
    *pDeviceInfo)
    /* Pointer to device info */

DESCRIPTION
This function returns information about a device. The following structure is defined for use with this function:
typedef struct {
    VpLineCtxType *pLineCtx; /* Pointer to Line Context */
    VpDeviceIdType deviceId; /* Device identity */
    VpDevCtxType *pDevCtx; /* Pointer to device Context */
    VpDeviceType deviceType; /* Device Type */
    uint8 numLines; /* Number of lines */
} VpDeviceInfoType;

This function can be used in the following two ways:
1. If the pointer to the line context (pDeviceInfo->pLineCtx) is not VP_NULL, then this function returns information about the device associated with the given line context. It fills all other elements in the VpDeviceInfoType struct. The identity of the device is stored in the deviceId field, a pointer to device context is stored in the pDevCtx field, the type of device is stored in the deviceType field, and the number of lines supported by the device is stored in the numLines field.
2. If the pointer to the line context is VP_NULL and the pointer to the device context (pDeviceInfo->pDevCtx) is not VP_NULL, then this function returns other details like device identity, device type, and the number of lines supported by the device. No information is written to the line context. Note that the application can use this function in this mode to learn the number of lines supported by the device before creating line objects.

If pDeviceInfo is VP_NULL then this function returns an error. If both the pointer to the line context and the pointer to the device context are VP_NULL then this function also returns an error.

RETURNS
See VP-API-II Function Return Type, on page 10

EVENTS
GENERATED
None

DEVICES All

TERMINATIONS All 

3.4.7 VpGetLineInfo()

SYNTAX vpStatusType

VpGetLineInfo(
    VpLineInfoType *pLineInfo)    /* Pointer to line info */

DESCRIPTION
This function returns information about a line. The following structure is defined for use with this function:
typedef struct {
    VpDevCtxType *pDevCtx; /* Pointer to device Context */
    uint8 channelId; /* Channel identity */
    VpLineCtxType *pLineCtx; /* Pointer to Line Context */
    VpTermType termType; /* Termination Type */
    VpLineIdType lineId;    /* System-wide line identifier */
} VpLineInfoType;
This function can be used in the following two ways:
1. If the pointer to the device context (pLineInfo->pDevCtx) is not VP_NULL, then this function returns information for the line associated with the specified device context and channelId. It fills all other elements of the VpLineInfoType struct (pLineCtx, lineId and termType) with the requested data. If no line context is associated with the specified channelId, then this function writes VP_NULL to the line context pointer.
2. If pDevCtx is VP_NULL, and pLineInfo->pLineCtx (the pointer to the line context) is not VP_NULL, then this function returns information for the line associated with the specified line context. It fills all other elements of the VpLineInfoType struct (pDevCtx, channelId, and termType) with the requested data.
If pLineInfo is VP_NULL then this function returns an error. If both the pointer to the line context and the pointer to the device context are VP_NULL then this function also returns an error.
RETURNS
See
    VP-API-II Function Return Type, on page 10
EVENTS
GENERATED
None
DEVICES All
TERMINATIONS All 

3.4.8 VpMapLineId()

SYNTAX vpStatusType

VpMapLineId(

VpLineCtxType *pLineCtx, /* Pointer to line context */ VpLineIdType lineId) /* Value assigned as line Id */

DESCRIPTION

This function can be used to assign a system-wide identification (lineId) to a given line. This identifier is not used by the VP-API-II and is reported along with the event in the VpGetEvent() and VpGetLineInfo() functions. The line identifier (VpLineIdType) is defined as a user defined type that can be modified by the implementation.

RETURNS

See VP-API-II Function Return Type, on page 10

EVENTS

GENERATED

None

DEVICES All

TERMINATIONS All

4.1 OVERVIEW

This chapter covers the VP-API-II options that are controlled by the application software at run-time. Each option is described using the following format:

DESCRIPTION This is a summary description of the option.

DEFAULT This field contains the default setting for the option.

DEVICES This field lists the devices that support the option.

This chapter discusses the individual option types that are accessed through the VpSetOption() and VpGetOption() functions. See VpSetOption(), on page 100 and VpGetOption(), on page 112 for complete descriptions of these functions.

4.2 OPTION SUMMARY

VpOptionIdType defines the set of options that VpSetOption() and VpGetOption() can write and read, respectively. Table 4-1 lists all valid options along with the applicable VTD and termination types. Each option is described in detail later in this chapter. Note that most options are automatically set to default values by the VP-API-II when the VTD is initialized. The default option settings are defined in vp_api_cfg.h.

Some options apply to individual lines, while other options apply to an entire VTD and all lines controlled by it. Global device option names begin with VP_DEVICE_OPTION_ID_. All other option names begin with VP_OPTION_ID_. The type of option (device-specific or line-specific) combined with the pLineCtx and pDevCtx arguments determine which line's configuration is accessed. See VpSetOption() Behavior, on page 100 and VpGetOption() Behavior, on page 112 for details.

Table 4-1 Available options

Options Devices Page
VP_DEVICE_OPTION_ID_PULSE All		31
VP_DEVICE_OPTION_ID_CRITICAL_FLT All		33
VP_OPTION_ID_ZERO_CROSS All		33
VP_OPTION_ID_PULSE_MODE All		34
VP_OPTION_ID_TIMESLOT All		34
VP_OPTION_ID_CODEC	All	35
VP_OPTION_ID_PCM_HWY	All	35
VP_OPTION_ID_LOOPBACK All		35
VP_OPTION_ID_LINE_STATE All		36
VP_OPTION_ID_EVENT_MASK All		37
VP_OPTION_ID_RING_CNTRL All		38
VP_OPTION_ID_DTMF_MODE	All	39
VP_OPTION_ID_PCM_TXRX_CNTRL	All	40

Table 4-1 Available options

VP_DEVICE_OPTION_ID_DEV_IO_CFG	VCP2, VE792	40
VP_OPTION_ID_LINE_IO_CFG	VCP2, VE792	41
VP_OPTION_ID_DTMF_SPEC	VCP2, VE792	43
VP_DEVICE_OPTION_ID_PARK_MODE	VCP2-792, VE792	43
VP_OPTION_ID_PULSE	VCP2-792, VE792	44
VP_OPTION_ID_DCFEED_SLOPE	VCP2-792, VE792, MeLT	46
VP_OPTION_ID_DEBUG_SELECT All		46
VP_OPTION_ID_HOOK_DETECT_MODE	VCP2-792, VE792	47
VP_DEVICE_OPTION_ID_PCM_SIG_CTL VE792		48
VP_OPTION_ID_LINEAR_CTL_MODE VE792		49

4.3 OPTION DESCRIPTIONS

4.3.1 VP\_DEVICE\_OPTION\_ID\_PULSE

DESCRIPTION

The option applies only if pulse detection is enabled on the line using VP_OPTION_ID_PULSE_MODE.

The pulse options allow the application to set the timing limits used by the VP-API-II/VTD to decode pulse digits and hook-switch flashes. All of the times are in units of 125 s. This option is device-specific and applies to all lines controlled by the VTD. Pulse option parameters are passed through the VpOptionPulseType structure shown below.

typedef struct {
    uint16 breakMin; /* Minimum pulse break time */
    uint16 breakMax; /* Maximum pulse break time */
    uint16 makeMin; /* Minimum pulse make time */
    uint16 makeMax; /* Maximum pulse make time */
    uint16 interDigitMin; /* Minimum pulse interdigit time. */
    uint16 flashMin; /* Minimum flash break time */
    uint16 flashMax; /* Maximum flash break time */
    uint16 onHookMin; /* Minimum on-Hook time */
} VpOptionPulseType; 

The timing limits set by the application must conform to the following relationships:

1. breakMin < breakMax < flashMin < flashMax < onHookMin
2. makeMin < makeMax < interDigitMin

Figure 4-1 shows an example of a typical setting for this option. It also shows the timing relationship between the dialed digit and the events generated.

Notes:

1. Parameter onHookMin is compiled out of the VP-API-II by default and is not accessible by applications. To enable onHookMin, the value EXTENDED_FLASH_HOOK must be changed to #define in file vp_api_cfg.h.
2. In VE792 applications, (breakMax > flashMin) is allowed. With this setting, if a pulse is detected with length between breakMax and flashMin, both the VP_LINE_EVID_PULSE_DIG (digit 1) and VP_LINE_EVID_FLASH events are generated.

Figure 4-1 Typical VP Option Pulse Timing Diagrams

Loop Close (Make) Loop Open (Break) Typical Break = 60 ms Break Min (t_bmin) = 47 ms Break Max (t_bmax) = 80 ms Max (60% @ 10 pps) Max (56% @ 12 pps) Max (64% @ 8 pps) Max (40% @ 10 pps) Max (36% @ 12 pps) Max (44% @ 8 pps) Max (40% @ 10 pps) Max (36% @ 12 pps) Max (44% @ 8 pps)

graph LR
    A["Start Pulse Event"] --> B["Break"]
    B --> C["Interdigit Min"]
    C --> D["Digit Event Generated (Digit = 3)"]

graph LR
    A["Make"] --> B["Break"]
    B --> C["Flash Hook"]
    C --> D["flashMin flashMax"]
    D --> E["flashMin and flashMax time"]
    style E fill:#f9f,stroke:#333,stroke-width:2px

graph TD
    A["Make"] --> B["Break"]
    B --> C{flashMax}
    C --> D["onHookMin"]
    D --> E["Extended Flash Hook Event Generated if return to "make" in between flashMax and onHookMin time"]

On-Hook Event is generated if "break" is longer than onHookMin time

DEFAULT

VpOptionPulseType::breakMin = 33 * 8; /* 33 milliseconds */

VpOptionPulseType::breakMax = 100 * 8; /* 100ms */

VpOptionPulseType::makeMin = 17 * 8; /* 17ms */

VpOptionPulseType::makeMax = 75 * 8; /* 75ms */

VpOptionPulseType::interDigitMin = 250 * 8; /* 250ms */

VpOptionPulseType::flashMin = 250 * 8; /* 250ms */

VpOptionPulseType::flashMax = 1300 * 8; /* 1300ms */

VpOptionPulseType::onHookMin = 1300 * 8; /* 1300ms */

DEVICES All

4.3.2 VP\_DEVICE\_OPTION\_ID\_CRITICAL\_FLT

DESCRIPTION

This option determines whether or not a line is automatically forced into Disconnect state when a critical fault (AC, DC, or thermal fault) is detected on that line. Placing the line in the Disconnect state (VP_LINE_DISCONNECT) involves putting the SLIC device into the Disconnect mode and putting the LCAS, if present, in the All-Off mode. This option is device-specific and applies to all lines controlled by the VTD. Critical fault option parameters are passed through the VpOptionCriticalFltType structure shown below.

typedef struct {
    bool acFltDiscEn;
    bool dcFltDiscEn;
    bool thermFltDiscEn;
} VpOptionCriticalFltType; 

Setting acFltDiscEn, dcFltDiscEn, or thermFltDiscEn to TRUE enables automatic disconnect when an AC, DC, or thermal fault is detected, respectively.

Notes:

1. The relay state (if a relay is defined in the termination type) is set to the least harmful setting allowed by the configuration without applying Ringing to the subscriber line. The application should set the relay to VP_RELAY_NORMAL using VpSetRelayState() to return to normal operation.

DEFAULT VpOptionCriticalFltType::acFltDiscEn= TRUE;
VpOptionCriticalFltType::dcFltDiscEn= TRUE;
VpOptionCriticalFltType::thermFltDiscEn= TRUE; 

DEVICES All

4.3.3 VP\_OPTION\_ID\_ZERO\_CROSS

DESCRIPTION

This option controls the precise relay behavior used to exit ringing near the zero cross point. Make-before-Break provides a continuous feed to the line, Break-before-Make provides a slight disconnect duration while exiting ringing, and None removes ringing immediately (i.e., does not wait for zero crossing).

This option is line-specific and is passed through a variable of type VpOptionZeroCrossType, shown below.

Enumeration Data Type: VpOptionZeroCrossType:
VP_OPTION_ZC_M4B /* Zero-Cross control - make-before-break */
VP_OPTION_ZC_B4M /* Zero-Cross control - break-before-make */
VP_OPTION_ZC_NONE /* Turn Zero-Cross Control OFF */ 

Notes:

1. The VTD relay setting must be in VP_RELAY_NORMAL for the VTD to control either variation of the Zero-Cross Control Option. If the relay setting is not set to VP_RELAY_NORMAL, then the proper timing and control will not occur (no operation of the relay will occur at all) and any operation pertaining to the relay control for ring entry or exit will be the host's responsibility.
2. The VP_OPTION_ZC_NONE zero-cross option is not supported for the VE792devices.

DEFAULT VP_OPTION_ZC_M4B

DEVICES All

4.3.4 VP\_OPTION\_ID\_PULSE\_MODE

DESCRIPTION

The pulse mode option determines whether automatic flash and pulse-digit decode is enabled for a particular line. This option is line-specific. This option is passed through a variable of type VpOptionPulseModeType, shown below.

Enumeration Data Type: VpOptionPulseModeType:
VP_OPTION_PULSE_DECODE_OFF
VP_OPTION_PULSE_DECODE_ON
VP_OPTION_PULSE_DECODE_BRIDGING 

The VP_OPTION_PULSE_DECODE_BRIDGING value enables a special bridging behavior in the pulse digit decoder. In this mode, all "runt" pulses (in which the break duration is less than breakMin) are ignored.

Notes:

1. When the VP_OPTION_PULSE_DECODE_BRINGING mode is enabled, the VP_LINE_EVID_STARTPULSE event will not occur until the breakMin interval has elapsed. Therefore, in this mode, the VP_LINE_EVID_STARTPULSE occurs slightly later than in the normal VP_OPTION_PULSE_DECODE_ON mode.

DEFAULT VP_OPTION_PULSE_DECODE_OFF

DEVICES All

4.3.5 VP\_OPTION\_ID\_TIMESLOT

DESCRIPTION

The timeslot option selects the PCM transmit and receive timeslots for the given line. PCM timeslots are numbered from 0 to max_num_timeslots-1, where max_num_timeslots equals f_PCLK KHz / 8 KHz / 8 bits. This option is line-specific. Timeslot option parameters are passed through the VpOptionTimeslotType structure shown below.

typedef struct {
    uint8 tx; /* 8-bit Transmit timeslot */
    uint8 rx; /* 8-bit Receive timeslot */
} VpOptionTimeslotType; 

When operating in linear PCM mode, or when executing a transmission-type line testing activity, the VP_OPTION_ID_TIMESLOT option specifies the first of 2 contiguous timeslots used by the line.

Notes:

1. The transmit direction refers to the data transmission from Tip/Ring towards the network. Receive direction refers to receiving the data from the network to Tip/Ring.
2. The application should assign timeslots before activating the device's PCM interface. See VpSetLineState(), on page 90 for more information on which line states activate the PCM highway.

DEFAULT None

DEVICES All

4.3.6 VP\_OPTION\_ID\_CODEC

DESCRIPTION

The codec option selects the PCM encoding algorithm for the given line. This option is line-specific. This option is passed through a variable of type VpOptionCodecType, shown below.

Enumeration Data Type: VpOptionCodecType:
VP_OPTION_ALAW /* Select G.711 A-law PCM encoding */
VP_OPTION_MLAW /* Select G.711 Mu-law PCM encoding */
VP_OPTION_LINEAR /* Select Linear PCM encoding */ 

Notes:

1. The VTD requires two adjacent 8-bit timeslots when in 16-bit linear PCM mode. The timeslot assigned by VP_OPTION_ID_TIMESLOT, on page 34 is the lowest numbered timeslot of the two timeslots occupied by a single channel in linear mode. Therefore, the host must not assign the next adjacent timeslot to any other line.

DEFAULT VP_OPTION_ALAW

DEVICES All

4.3.7 VP\_OPTION\_ID\_PCM\_HWY

DESCRIPTION

The PCM highway option selects the PCM highway for the given line. This option is line-specific. This option is passed through a variable of type VpOptionPcmHwyType, shown below.

Enumeration Data Type: VpOptionPcmHwyType:
VP_OPTION_HWY_A/* Select the "A" PCM Highway */
VP_OPTION_HWY_B/* Select the "B" PCM Highway */
VP_OPTION_HWY_TX_A_RX_B/* Transmit on "A", receive on "B" */
VP_OPTION_HWY_TX_B_RX_A/* Transmit on "B", receive on "A" */
VP_OPTION_HWY_TX_AB_RX_A/* Transmit on "A" and "B", receive on "A" */
VP_OPTION_HWY_TX_AB_RX_B/* Transmit on "A" and "B", receive on "B" */ 

DEFAULT VP_OPTION_HWY_A

DEVICES All

4.3.8 VP\_OPTION\_ID\_LOOPBACK

DESCRIPTION

The loopback option controls the loop back mode of the given line. This option is line-specific. This option is passed through a variable of type VpOptionLoopbackType, shown below.

Enumeration Data Type: VpOptionLoopbackType:
VP_OPTION_LB_OFF /* All loopbacks off */
VP_OPTION_LB_TIMESLOT /* Perform a timeslot loopback */
VP_OPTION_LB_DIGITAL /* Perform a full-digital loopback */ 

VP_OPTION_LB_TIMESLOT loopbacks the line at the device internal timeslot manager. Digital signals output from the TX path will match those provided in the RX path.

VP_OPTION_LB_DIGITAL loopbacks the line in the A/D-D/A section. Digital signals output from the TX path will not match those provided in the RX path due to programmed AC coefficients and line impedance.

Refer to the device's Chip Set User's Guide for further details.

If the device controlled by the VP-API-II supports different battery levels, then the line state option allows for these modifiers to be applied to the appropriate line state. Thus, when a line of the device is subsequently placed in a particular state, the modifiers defined by the line state option are automatically applied where appropriate. This option is passed through the VpOptionLineStateType structure shown below.

typedef struct {
    bool battRev; /* Smooth/abrupt Bat reversal; TRUE=abrupt */
    VpOptionBatType bat; /* Battery selection for active line states */
} VpOptionLineStateType; 

When the battRev variable is set to FALSE, it forces a smooth voltage change when the line state is changed from any of the following states: VP_LINE_ACTIVE, VP_LINE_ACTIVE_POLREV, VP_LINE_STANDBY, VP_LINE_STANDBY_POLREV, VP_LINE_OHT, VP_LINE_OHT_POLREV, VP_LINE_TALK, and VP_LINE_TALK_POLREV to the corresponding state of opposite polarity. The smooth ramp time varies with the device and is not programmable. Any other state transition (including polarity reversals with the battRev variable is set to TRUE) uses the abrupt mode. Behavior in abrupt mode depends on the specific device.

- Abrupt behavior definition for VE792 device: The rate of change is programmable via option VP_OPTION_ID_DCFEED_SLOPE and affects all DC Feed changes. The rate may be faster or slower than smooth polarity reversal setting.

The bat battery modifier option can be any of the following enumeration constants:

Enumeration Data Type: VpOptionBatType:
VP_OPTION_BAT_AUTO /* Automatic battery selection */
VP_OPTION_BAT_HIGH /* Use VBH and GND for active line states */
VP_OPTION_BAT_LOW /* Use VBL and GND for active line states */
VP_OPTION_BAT_BOOST /* Use VBH and VBP for active line states */ 

See the device's Chip Set User's Guide for further information about polarity and battery levels. Note that the specific modifier options available depend upon the device controlled by the VP-API-II.

Notes:

1. The vpoptionBatType option allows the application to minimize power dissipation due to DC feed by selecting the most appropriate battery supply for each line.
2. The battRev (i.e., smooth) battery reversal is used to minimize noise on the line during polarity reversals.

DEFAULT

VpOptionLineStateType::battRev = FALSE;
VpOptionLineStateType::bat = VP_OPTION_BAT_AUTO; 

DEVICES All

4.3.10 VP\_OPTION\_ID\_EVENT\_MASK

DESCRIPTION

This option determines which events are reported for a given line. This option is line-specific. The event mask option is passed though the VpOptionEventMaskType structure shown below.

typedef struct {
    uint16 faults; /* Fault event category masks */
    uint16 signaling; /* Signaling event category masks */
    uint16 response; /* Mailbox response event category masks */
    uint16 test; /* Test events */
    uint16 process; /* Call process event category masks */
} VpOptionEventMaskType; 

Masking an event is done by setting the corresponding event bit to '1', unmasking is done by setting the corresponding event bit to '0'. Masking an event prevents the event from being reported to the application (via VpGetEvent()). Undefined bits in the event mask should always be set to '1'. This prevents unexpected events from being generated should these undefined bits be defined in later software versions.

The composite masks for each event category are created by bitwise ORing the event ID constants of the individual events within that category. When building the composite event mask for a particular event category the application should only sum individual event ID constants belonging to that event category. The following enumeration types define the event ID constants in the source code:

• VpFaultEventType
• VpSignalingEventType
  • VpResponseEventType
• VpTestEventType
• VpProcessEventType

These event types are described in Chapter 5. Some event are device-specific, and some events are line-specific. Setting a device-specific event mask for an individual line effectively changes that mask for all other lines controlled by that VTD. To avoid confusion, the application should always set device-specific event masks for individual lines to the same value across all lines of a VTD. The application must take care not to accidentally change a device-specific event mask when modifying other event masks for an individual line. Refer to VpSetOption(), on page 100 for more information on how device-specific and line-specific options are applied based on the values of pDevCtx and pLineCtx.

Changing the event mask does not affect the actual processing of the line transitions. For example, if dial pulsing detection is enabled with dial pulsing events being masked and dial pulsing events are un-masked in the middle of detecting a digit 8 from the terminal, the digit event generated at the end of the pulse train will indicate a digit 8, not a digit 4.

Notes:

1. Changing the event mask does not affect events that are already in the event queue waiting to be delivered to the application. Therefore, it is possible for the application to receive an event even after having masked that type of event.

2. Some events are non-maskable. The mask bits corresponding to these events are ignored. Refer to Chapter 5 for details.

DEFAULT All events are masked except for non-maskable events.

DEVICES All

4.3.11 VP\_OPTION\_ID\_RING\_CNTRL

DESCRIPTION

This option configures the ring-trip attributes of a line. This option is line-specific. The ring-trip control option is passed though the VpOptionRingControlType structure shown below.

typedef struct {
    VpOptionZeroCrossType zeroCross;
    uint16 ringExitDbncDur;
    VpLineStateType ringTripExitSt;
} VpOptionRingControlType; 

The zeroCross parameter controls exactly the same setting as the VP_OPTION_ID_ZERO_CROSS option. That is, VP_OPTION_ID_RING_CNTRL and VP_OPTION_ID_ZERO_CROSS modify the same behavior. The only difference is that VP_OPTION_ID_RING_CNTRL allows the application to set the ring-exit debounce time and ring-exit line state as well. See VP_OPTION_ID_ZERO_CROSS, on page 33 for more information on zero-cross control settings.

The ringExitDbncDur variable sets the minimum time to ignore hook activity when exiting ringing, specified in units of 125 s. The ring-exit debounce period set by the user starts no earlier than when ringing is removed from the line, which may be up to 1/2 period from the time the application stops ringing by either calling VpSetLineState() or by a ringing cadencing operation.

This debounce time helps filter false hook events during transitions from the ringing-on state to the ringing-off state caused by the physical characteristics of the line. Ring-exit hook debouncing can be disabled by setting this variable to 0.

The ringTripExitSt parameter determines which state the line is automatically switched to when ring-trip occurs. This feature can be effectively disabled by setting ringTripExitSt to the active ringing state (i.e. VP_LINE_RINGING or VP_LINE_RINGING_POLREV).

Notes:

The VE792 devices do not allow ringing into an off-hook phone. If ringTripExitSt is set to VP_LINE_RINGING or VP_LINE_RINGING_POLREV the line will put the line in a feed state when ring-trip occurs but will report VP_LINE_RINGING (or VP_LINE_RINGING_POLREV) when VpGetLineState() is called. The application should then call VpSetLineState() with a non-ringing state to provide normal operation.

DEFAULT VpOptionRingControlType::zeroCross = VP_OPTION_ZC_M4B;
VpOptionRingControlType::ringExitDbncDur = 100 * 8; /* 100ms */
VpOptionRingControlType::ringTripExitSt = VP_LINE_TALK; 

DEVICES All

4.3.12 VP\_OPTION\_ID\_DTMF\_MODE

DESCRIPTION

This option configures DTMF detection for a given line. This option is line-specific. The DTMF mode option is passed though the VpOptionDtmfModeControlType structure shown below.

typedef struct {
    VpOptionDtmfModeControlType dtmfControlMode;
    VpDirectionType direction;
    uint32 dtmfDetectionSetting;
    uint8 dtmfResourcesRemaining;
    uint8 dtmfDetectionEnabled[VP_LINE_FLAG_BYTES]
} VpOptionDtmfModeType; 

The dtmfControlMode parameter determines whether DTMF detection is enabled, disabled, or unchanged when this option is set. This variable can take any of the following values:

Enumeration Data Type: VpOptionDtmfModeControlType:
VP_OPTION_DTMF_DECODE_OFF /* Turn OFF DTMF decoding */
VP_OPTION_DTMF_DECODE_ON /* Turn ON DTMF decoding */
VP_OPTION_DTMF_GET_STATUS /* Just get the status of DTMF resources */ 

If dtmfControlMode is set to VP_OPTION_DTMF_GET_STATUS then the DTMF detection setting is unchanged, and the dtmfDetectionSetting and dtmfResourcesRemaining variables are updated.

The direction parameter determines whether DTMF detection is performed in the upstream (VP_DIRECTION_US) or downstream (VP_DIRECTION_DS) direction. VE792 devices only support upstream DTMF detection.

Each bit in the dtmfDetectionEnabled field represents the DTMF detection setting of a line controlled by the VTD. This variable is overwritten by the VP-API-II with the current DTMF detection settings when VpSetOption() is called.

The number of array elements, VP_LINE_FLAG_BYTES = (VP_MAX_LINES_PER_DEVICE + 7) / 8, is the number of eight-bit integers required to store a flag for each channel in the device. VP_MAX_LINES_PER_DEVICE is a compile-time option defined in vp_api_cfg.h. Bit 0 in array element 0 represents line 0, bit 1 represents line 1, and so on. Bit 0 in array element 1 represents line 8.

The dtmfDetectionSetting field contains the same data as the first four elements of the dtmfDetectionEnabled array. This field is included for backward-compatibility. For devices with more than 32 lines, this variable only contains information about the first 32 lines.

The dtmfResourcesRemaining field indicates the number of DTMF detection resources available after applying the current option setting. VE792 devices support DTMF detection on all channels simultaneously, so this field can be ignored.

1. 2.

DEFAULT VpOptionDtmfModeType::dtmfControlMode = VP_OPTION_DTMF_DECODE_OFF; VpOptionDtmfModeType::direction = VP_DIRECTION_US;

DEVICES All

4.3.13 VP\_OPTION\_ID\_PCM\_TXRX\_CNTRL

DESCRIPTION

This line-specific option enables or disables the PCM transmit and receive paths in line states that use the PCM highway, including: VP_LINE_TALK, VP_LINE_TALK_POLREV, VP_LINE_OHT, and VP_LINE_OHT_POLREV. This option can take any of the following values:

Enumeration Data Type: VpOptionPcmTxRxCntrlType:
VP_OPTION_PCM_BOTH /* Enable PCM transmit and receive paths */
VP_OPTION_PCM_RX_ONLY /* Enable PCM receive path only */
VP_OPTION_PCM_TX_ONLY /* Enable PCM transmit path only */ 

Notes:

1. Line state transitions (requested through VpSetLineState(), on page 90) do not change this option.

DEFAULT VP_OPTION_PCM_BOTH 

DEVICES All

4.3.14 VP\_DEVICE\_OPTION\_ID\_DEV\_IO\_CFG

DESCRIPTION

This option configures the general-purpose input/output (GPIO) pins controlled by a device.

The arguments to this option are passed to VpSetOption() in a VpOptionDeviceIoConfigType struct:

typedef struct {
    VpOptionLineIoConfigType lineIoConfig[VP_MAX_LINES_PER_DEVICE];
    VpOptionDeviceIoConfigType; 

where VP_MAX_LINES_PER_DEVICE is a compile-time option calculated in vp_api_cfg_int.h. The value is 8 for VE792 devices.

The lineIoConfig array (indexed by channel ID) contains a VpOptionLineIoConfigType struct for each line controlled by the device. For each element of lineIoConfig, the array index equals the channel ID. Please see VP_OPTION_ID_LINE_IO_CFG, on page 41 for further information about VpOptionLineIoConfigType.

DEFAULT None; VTDs retain their hardware reset value.

DEVICES VCP2, VE792

4.3.15 VP\_OPTION\_ID\_LINE\_IO\_CFG

DESCRIPTION

This option configures the general-purpose input/output (GPIO) pins associated with a particular line. The number of I/O pins configurable through this option for each line is dictated by the reference design (VTD and line termination type) being used. I/O pins that are reserved by the reference design for driving LCAS devices or relays (using the VpSetRelayState() function) cannot be configured by this option.

The arguments to this option are passed to VpSetOption() in a VpOptionLineIoConfigType struct:

typedef struct {
    uint8 direction;
    uint8 outputType;
} VpOptionLineIoConfigType; 

Up to eight GPIO pins per channel can be configured. Each bit in the direction field specifies for an individual GPIO pin whether it is an input (0) or output (1). The corresponding bit in the outputType field specifies whether the pin (if configured as an output) is a TTL/CMOS output (0) or open-collector/open-drain (1) output.

typedef enum {
    VP_IO_INPUT_PIN = 0,
    VP_IO_OUTPUT_PIN = 1
} VpDeviceIoDirectionType;

typedef enum {
    VP_OUTPUT_DRIVEN_PIN = 0,
    VP_OUTPUT_OPEN_PIN = 1
} VpDeviceOutputPinType; 

The following table shows for each VTD and line termination type which GPIO pins can be configured by setting the corresponding bits in the direction and outputType fields. Bits that are 0 in the table are ignored in these fields.

Table 4-2

VTD(s) Line Termination Type Bitmask
VE792	VP_TERM_FXS_TI 00000010
	VP_TERM_FXS_GENERIC 00000011
	VP_TERM_FXS_RR 00000010
	VP_TERM_FXS_RR_TI 0000000

This option only controls the configuration of an I/O pin. Read or write of the I/O pin data is done using the VpLineIoAccess(), on page 102 or VpDeviceIoAccessExt(), on page 103.

DEFAULT None, VTDs retain their hardware reset value.

DEVICES VCP2, VE792

4.3.16 VP\_OPTION\_ID\_DTMF\_SPEC

DESCRIPTION

This option selects the DTMF detection criteria (based on region specifications) to be associated with a particular line.

The acceptable values for this option are given in the VpOptionDtmfSpecType enumeration:

Enumeration Data Type: VpOptionDtmfSpecType:
VP_OPTION_DTMF_SPEC_ATT /* Q.24 AT&T */
VP_OPTION_DTMF_SPEC_NTT /* Q.24 NTT */
VP_OPTION_DTMF_SPEC_AUS /* Q.24 Australian */
VP_OPTION_DTMF_SPEC_BRZL /* Q.24 Brazilian */
VP_OPTION_DTMF_SPEC_ETSI /* ETSI ES 201 235-3 v1.3.1 */ 

DEFAULT VP_OPTION_DTMF_SPEC_ATT

DEVICES VCP2, VE792

4.3.17 VP\_DEVICE\_OPTION\_ID\_PARK\_MODE

DESCRIPTION

This option selects the disconnect and standby (line states) interval durations while the line is in VP_LINE_PARK state.

The arguments to this option are passed to VpSetOption() in a VpOptionParkModeType struct:

typedef struct {
    uint16 discTime; /* Specified in 500ms increment, up to 8 seconds */
    uint16 standbyTime; /* Specified in 100ms increment, up to 8 seconds */
} VpOptionParkModeType; 

Value of 0 for either discTime or standbyTime are invalid.

The time to transition out of the disconnect to standby time is defined by VP_OPTION_ID_DCFEED_SLOPE. While in disconnect and during ramp to standby time, changes to hook status are masked. The application should take into account the disconnect to standby time when setting the value standbyTime in VP_DEVICE_OPTION_ID_PARK_MODE in order to allow sufficient time in DC Feed region to detect an on-hook.

Figure 4-2 Park Mode Timing

graph LR
    A["High Impedance"] --> B["DC Feed"]
    C["t_dc: time set by VP_OPTION_ID_DCFEED_SLOPE"] --> D["discTime standbyTime"]
    style A fill:#f9f,stroke:#333
    style B fill:#ccf,stroke:#333
    style C fill:#cfc,stroke:#333
    style D fill:#fcc,stroke:#333

DEFAULT VpOptionParkModeType::discTime = 4; /* 2 seconds */ VpOptionParkModeType::standbyTime = 3; /* 300ms */

DEVICES VCP2-792, VE792

4.3.18 VP\_OPTION\_ID\_PULSE

DESCRIPTION

This option is nearly identical to VP_DEVICE_OPTION_ID_PULSE, except configures dial pulse parameters specific to the line rather than all lines of the device and contains an additional parameter to allow added off-hook verification applied to the first off-hook.

Pulse option parameters are passed through the VpOptionLinePulseType structure shown below.

typedef struct {
    uint16 breakMin; /* Minimum pulse break time */
    uint16 breakMax; /* Maximum pulse break time */
    uint16 makeMin; /* Minimum pulse make time */
    uint16 makeMax; /* Maximum pulse make time */
    uint16 interDigitMin; /* Min. pulse interdigit time. */
    uint16 flashMin; /* Minimum flash break time */
    uint16 flashMax; /* Maximum flash break time */
    uint16 onHookMin; /* Minimum on-Hook time */
    uint16 offHookMin; /* Minimum off-Hook time */
} VpOptionLinePulseType; 

All parameters except for offHookMin have been discussed in VP_DEVICE_OPTION_ID_PULSE.

Value offHookMin allows the application to define a time that delays reporting of VP_LINE_EVID_HOOK_OFF for an off-hook that occurs after VP_LINE_EVID_HOOK_ON (i.e., steady state on-hook). When set to 0, behavior is identical to VP_DEVICE_OPTION_ID_PULSE. When set > 0, event VP_LINE_EVID_HOOK_PREQUAL is generated (at time of device hook debounce completion) prior to VP_LINE_EVID_HOOK_OFF.

Figure 4-3 Off-Hook Min Timing
Case 1: offHookMin set > 0

graph TD
    A["Event Data = VP_HOOK_PREQUAL_START"] --> B["Loop Close (Make)"]
    C["Event Data = VP_HOOK_PREQUAL_START"] --> D["Loop Open (Break)"]
    E["Off Hook Min"] --> F["Loop Close (Make)"]
    G["Off Hook Min"] --> H["Loop Open (Break)"]
    I["Event Data = VP_HOOK_PREQUAL_ABORT"] --> J["Loop Close (Make)"]
    K["Event Data = VP_HOOK_PREQUAL_ABORT"] --> L["Loop Open (Break)"]
    M["Event Data = VP_HOOK_PREQUAL_ABORT"] --> N["Loop Close (Make)"]
    O["Event Data = VP_HOOK_PREQUAL_START"] --> P["Loop Open (Break)"]
    Q["Event Data = VP_HOOK_PREQUAL_START"] --> R["Loop Close (Make)"]
    S["Event Data = VP_HOOK_PREQUAL_START"] --> T["Loop Open (Break)"]
    U["Event Data = VP_HOOK_PREQUAL_OFF"] --> V["Loop Close (Make)"]
    W["Event Data = VP_HOOK_PREQUAL_OFF"] --> X["Loop Open (Break)"]
    Y["Off Hook Min"] --> Z["Loop Close (Make)"]
    AA["Off Hook Min"] --> AB["Loop Open (Break)"]

Case 2: offHookMin set = 0

VP_LINE_EVID_HOOK_OFF Loop Close (Make) Loop Open (Break) t_hw = SLAC hardware hook debounce time (set in DC Profile)

Notes:

1. Parameter onHookMin is compiled out of the VP-API-II by default. To enable onHookMin, the value EXTENDED_FLASH_HOOK must be changed to #define in file vp_api_cfg.h.
2. When the onHookMin parameter is not used, the minimum on-hook duration required to generate an on-hook event is set by the flashMax parameter.
3. Setting VP_OPTION_ID_PULSE after VP_DEVICE_OPTION_ID_PULSE overrides the pulse detection parameters of the line. Setting VP_DEVICE_OPTION_ID_PULSE after VP_OPTION_ID_PULSE overrides all lines of the device. Parameters set by previous calls with VP_OPTION_ID_PULSE will be overwritten.
4. In VE792 applications, (breakMax > flashMin) is allowed. With this setting, if a pulse is detected with length between breakMax and flashMin, a VP_LINE_EVID_FLASH event is generated with eventdata = VP_FLASH_AND_DIGIT1.
5. In the VP_LINE_STANDBY and VP_LINE_STANDBY_POLREV line states, the VA and VB ADCs are turned off to save power. This imposes an additional 7 ms of off-hook-detection time before the standard hardware debounce interval (DSH) begins. Therefore in these line states, the effective offHookMin interval will be 7 ms greater than the value programmed in the VP_OPTION_ID_PULSE option.

In all other line states (VP_LINE_ACTIVE, VP_LINE_TALK, etc.) this does not apply; the effective offHookMin interval will match the programmed value.

DEFAULT

VpOptionLinePulseType::breakMin	= 33 * 8;	/* 33 milliseconds */
VpOptionLinePulseType::breakMax	= 100 * 8;	/* 100ms */
VpOptionLinePulseType::makeMin	= 17 * 8;	/* 17ms */
VpOptionLinePulseType::makeMax	= 75 * 8;	/* 75ms */
VpOptionLinePulseType::interDigitMin	= 250 * 8;	/* 250ms */
VpOptionLinePulseType::flashMin	= 250 * 8;	/* 250ms */
VpOptionLinePulseType::flashMax	= 1300 * 8;	/* 1300ms */
VpOptionLinePulseType::onHookMin	= 1300 * 8;	/* 1300ms */
VpOptionLinePulseType::offHookMin	= 0 * 8;	/* 0ms */

DEVICES VCP2-792, VE792

4.3.19 VP\_OPTION\_ID\_DCFEED\_SLOPE

DESCRIPTION

This option is provided to define the rate of DC Feed changes in order to maintain IVD friendliness.

By default, this setting affects all transitions (except polarity reversal when battRev = FALSE). When option VP_OPTION_ID_LINE_STATE is set for abrupt polarity reversal (battRev = TRUE), then DC Feed change rate for polarity reversals are also controlled by this option.

The VpSetOption() function accepts a single parameter for this option value:

uint16 slopeRate;

The slopeRate value specifies the maximum voltage change over a 125- s period using the following equation:

$$ \text { tip_ring_slope } := \frac {(\text { slopeRate } \cdot 1 5 0)}{2 ^ {1 5}} $$

With slopeRate = 109, |Tip - Ring| voltage can change at a rate of 0.5 V / 125 μs or 4 V / ms. The valid range is 0 to 32767.

Notes:

Setting slopeRate = 0 will produce a slope of infinite duration, preventing polarity reversals.

DEFAULT

uint16 slopeRate = 109;

DEVICES VCP2-792, VE792, MeLT

4.3.20 VP\_OPTION\_ID\_DEBUG\_SELECT

DESCRIPTION

The debug capabilities of the VP-API-II and configuration are discussed in Chapter 13

DEFAULT

See Chapter 13

DEVICES All

4.3.21 VP\_OPTION\_ID\_HOOK\_DETECT\_MODE

DESCRIPTION

This option enables an alternate hook detection behavior when entering and exiting the VP_LINE_DISCONNECT and other hook-disabled line states. In these line states, hook state detection is not possible, because the SLIC is not driving a DC feed current.

The hook-disabled line states are VP_LINE_DISCONNECT, VP_LINE_DISABLED, VP_LINE_NULL_FEED, VP_LINE_TIP_OPEN, VP_LINE_RING_OPEN, and VP_LINE_TESTING.

The acceptable values for this option are given in the VpOptionHookDetectModeType enumeration:

Enumeration Data Type: VpOptionHookDetectModeType:
VP_OPTION_HOOKDET_NORMAL    /* normal (default) behavior */
VP_OPTION_HOOKDET_DISC_IS_ONHOOK/* DISCONNECT is "on-hook" */ 

In the VP_OPTION_HOOKDET_NORMAL mode, the hook state retains its current value when entering a hook-disabled line state:

• In a hook-disabled line state, the hook state returned by VpGetLineStatus() and VpGetDeviceStatusExt() will be the same as the value reported before entering the hook-disabled state.
• No artificial hook events will be generated when entering or exiting these line states.

In the VP_OPTION_HOOKDET_DISC_IS_ONHOOK mode, the hook state is considered to be on-hook when the line state is in a hook-disabled state:

• When entering a hook-disabled line state, if the hook-state is off-hook, an artificial VP LINE EVID HOOK ON event will be generated.
• When the line is in a hook-disabled state, the hook state returned by VpGetLineStatus() and VpGetDeviceStatusExt() will always be on-hook.
• When exiting a hook-disabled line state, when normal hook detection resumes, if the line is still off-hook, an artificial VP_LINE_EVID_HOOK_OFF event will be generated.

DEFAULT VP OPTION HOOKDET NORMAL

DEVICES VCP2-792, VE792

TERMINATIONS FXS

4.3.22 VP\_DEVICE\_OPTION\_ID\_PCM\_SIG\_CTL

DESCRIPTION

This option enables PCM highway signaling and control mode for ZL792588 devices. (This option is not implemented for Le792388 and ZL792388).

Option parameters are passed using the VpOptionPcmSigCtlType structure shown below.

typedef struct {
    bool enable;
    uint8 ctlTimeslot;    /* Starting timeslot for signaling bits */
    uint8 sigTimeslot;    /* Starting timeslot for control bits */
} VpOptionPcmSigCtlType; 

When this option is enabled (enable = TRUE), four contiguous timeslots (32 bits) are reserved on the PCM highway in each direction for signaling and control. In the transmit direction, the first timeslot reserved for signaling bits (hook and ground-key indications) is specified by the sigTimeslot value. In the receive direction, the first timeslot reserved for control bits (line state and polarity) is specified by the ctlTimeslot value.

When this option is enabled, the SLAC puts the signaling bits onto the PCM highway in the following format (with the leftmost byte and bit numbered 0):

Table 4-3 Signaling Bits (Upstream)

Byte	Bits
	0	1	2	3	4	5	6	7
0		-	-	-	-	-	-	-
1	-	-		G 5	G	4	G 3	G 2
2		-	-	-	-	-	-	-
3	-	-	H5	H4	H3	H2	H1	H0

The fields containing “-” are reserved. For SLAC channel n, the hook bit Hn indicates on-hook (0) or off-hook (1). The ground-key bit Gn indicates active ground-key (1) or no active ground-key (0). The signaling bits are updated by the SLAC firmware at 2 kHz (0.5-ms intervals).

The format for the control bits is described elsewhere (See VP_OPTION_ID_LINESTATE_CTL_MODE, on page 49.)

Notes:

1. When this option is enabled, the ZL792588 behaves as a six-channel device. The last two channels (6 and 7) of the device are not usable.
2. PCM line state control must be enabled for each channel using the VP_OPTION_ID_LINESTATE_CTL_MODE option. Otherwise, the control bits are ignored for that channel.

DEFAULT VpOptionPcmSigCtlType::enable = FALSE;
VpOptionPcmSigCtlType::ctlTimeslot = 0;
VpOptionPcmSigCtlType::sigTimeslot = 0; 

DEVICES VE792 (ZL792588 only)

4.3.23 VP\_OPTION\_ID\_LINESTATE\_CTL\_MODE

DESCRIPTION

This option enables PCM highway line state control mode for a particular channel of a ZL792588 device. (This option is not implemented for Le792388 and ZL792388).

The acceptable values for this option are given in the VpOptionLinestateCtlModeType enumeration:

Enumeration Data Type: VpOptionLinestateCtlModeType:
VP_OPTION_LINESTATE_CTL_NORMAL    /* normal (default) behavior */
VP_OPTION_LINESTATE_CTL_PCM    /* PCM highway control */ 

When VP_OPTION_LINESTATE_CTL_PCM is selected for a particular channel, the SLAC reads the line state from the PCM highway at 1 kHz (1-ms intervals) for that channel. When VP_OPTION_LINESTATE_CTL_NORMAL is selected, the line state is specified by VpSetLineState(), as usual.

When VP_OPTION_LINESTATE_CTL_PCM is selected, the SLAC reads the control bits from the PCM highway in the following format (with the leftmost byte and bit numbered 0):

Table 4-4 Control Bits (Downstream)

Byte	Bits
	0	1	2	3	4	5	6	7
0		-	-	-	-	-	-	-
1 P5 ST5 P4		ST4
2 P3 ST3 P2		ST2
3 P1 ST1 P0		ST0

The fields containing “-” are reserved. For SLAC channel n, the polarity bit Pn indicates normal DC feed polarity (0) or reverse polarity (1). The STn field indicates the line state, decoded as follows:

Table 4-5 PCM Highway Line State Encoding

PnSTnLine State
x 0 0 0 VP	LINE	DISABLED
x 0 0 1 VP	LINE	DISCONNECT
x 0 1 0 VP	LINE	NULLFEED
0	0	1	1	V P _ L I N E _ S
1	0	1	1	V P _ L I N E _
0	1	0	0	V P _ L I N E _
1	1	0	0	V P _ L I N E _
0	1	0	1	V P _ L I N E _
1	1	0	1	V P _ L I N E _
x 1 1 0		VP_LINE_RINGING
x 1 1 1		VP_LINE_HOWLER

Notes:

1. The VP_DEVICE_OPTION_ID_PCM_SIG_CTL option must be enabled for the device, before enabling this option on any channel. Otherwise, the behavior is undefined.

DEFAULT

VP_OPTION_LINESTATE_CTL_NORMAL

DEVICES VE792 (ZL792588 only)

CHAPTER

5

EVENTS

Microsemi.

5.1 OVERVIEW

The VP-API-II uses an abstract event type to report VTD events to the host application. These events typically correspond to asynchronous VTD interrupts or occur as a result of some command issued by the application. VP-API-II events are organized into categories, with several events in each category. Each event may have some combination of a time stamp, a handle, event data, or event results attached to the event. This chapter covers all VP-API-II events in detail and describes the data types attached to each event. Each event description follows the format below:

DESCRIPTION

This is a summary description of the event and what causes it.

T.S. OR HANDLE

This section describes the parmHandle field of the VpEventType struct.

An event can have a time stamp, user defined handle, or event specific value associated with it.

• Event time stamps are reported as 16-bit integers in units of 0.5 ms.
- Event handles are 16-bit variables that the application can use to associate an event with a prior command. For some VP-API-II functions, the application can provide a handle that is returned with the event carrying the results for that function. The VP-API-II does not use the handle in any way; it simply passes the handle back to the application with an event. The application can use the handle for any purpose, or ignore it altogether.
- Some events use neither the time stamp nor the handle, in which case this field may be marked "N/A."

EVENT DATA

This section describes the eventdata field of the VpEventType struct.

Every event carries a 16-bit variable that may contain a small amount of data associated with the event. The meaning of this variable is described for each individual event. Some events do not use this variable, in which case this field is marked "N/A."

RESULTS

This section describes the hasResults field of the VpEventType struct.

Some events have data associated with them that is larger than the 16-bit event data variable. For those events, this field is set to TRUE.

The VP-API-II uses the concept of a mailbox to pass this data back to the application. The application can call VpGetResults() to retrieve the event data from the mailbox. The type of the result data is described in this section for each event. If an event has results associated with it but the application does not care about the results, the application must call VpClearResults() to empty the mailbox anyway.

Some events do not have such results, in which case this field is set to FALSE by the API and marked "N/A" in the documentation.

DEVICES This section lists the devices that can generate the event.

TERMINATIONS

This section lists the termination types that can generate the event. Termination type “All” means either all termination types supported by the applicable devices, or the termination type is not relevant to the event.

The VP-API-II functions related to event reporting are described elsewhere in this document.

- VpGetEvent(), on page 108

• VpFlushEvents(), on page 113

• VpGetResults(), on page 114
• VpClearResults(), on page 115
• VpSetOption(). on page 100 with VP OPTION ID EVENT MASK, on page 37
• VpGetOption(), on page 112 with VP OPTION ID EVENT MASK, on page 37

5.2 EVENT SUMMARY

Table 5-1 on page 53 lists all events that the VP-API-II can generate. The events are organized into categories, and these categories are defined in the software by the VpEventCategoryType enumeration. Notice that some events apply only to certain device types. The application will never receive an event that is not generated by the device type(s) used in the system.

Table 5-1 List of VP-API-II Events

Event ID Devices Terminations Page
Fault Events
VP_DEV_EVID_BAT_FLT All All			56
VP_DEV_EVID_CLK_FLT All All			56
VP_LINE_EVID_THERM_FLT All All			56
VP_LINE_EVID_DC_FLT VCP-790, VCP2, VE792, MeLT All			57
VP_LINE_EVID_AC_FLT VCP-790, VCP2, VE792, MeLT All			57
VP_DEV_EVID_EVQ_OFL_FLT VE792	All		57
VP_DEV_EVID_WDT_FLT	VE792	All	57
VP_DEV_EVID_SYSTEM_FLT	VCP2, VE792, MeLT	All	58
Signaling Events
VP_LINE_EVID_HOOK_OFF	All All		59
VP_LINE_EVID_HOOK_ON	All All		59
VP_LINE_EVID_GKEY_DET	All All		60
VP_LINE_EVID_GKEY_REL	All All		60
VP_LINE_EVID_FLASH	All	FXS	60
VP_LINE_EVID_STARTPULSE	All	FXS	60
VP_LINE_EVID_DTMF_DIG	All	FXS	61
VP_LINE_EVID_PULSE_DIG All	FXS		61
VP_LINE_EVID_MTONE	All All		62
VP_DEV_EVID_TS_ROLLOVER	All All		62
VP_LINE_EVID_EXTD_FLASH	VCP2-792, VE792	FXS	61
VP_LINE_EVID_HOOK_PREQUAL	VCP2-792, VE792	FXS	62
Response Events
VP_LINE_EVID_LLCMD_TX_CMP	All All		63
VP_LINE_EVID_LLCMD_RX_CMP	All All		63
VP_DEV_EVID_DNSTR_MBOX All All			63
VP_LINE_EVID_RD_OPTION All All			64
VP_LINE_EVID_RD_LOOP	All All		64
VP_EVID_CAL_CMP	All All		66
VP_EVID_CAL_BUSY All All			66
VP_LINE_EVID_GAIN_CMP All All			67
VP_DEV_EVID_DEV_INIT_CMP All All			67
VP_LINE_EVID_LINE_INIT_CMP All All			68
VP_DEV_EVID_IO_ACCESS_CMP All All			68
VP_LINE_EVID_LINE_IO_RD_CMP VCP2, VE792, MeLT-VCP All			68
VP_LINE_EVID_LINE_IO_WR_CMP VCP2, VE792, MeLT-VCP All			69
VP_LINE_EVID_QUERY_CMP VCP2-792, VE792, MeLT All			69
Test Events
VP_LINE_EVID_TEST_CMP All All			70
VP_LINE_EVID_DTONE_DET All FXS			70
VP_LINE_EVID_DTONE_LOSS All FXS			70
Process Events
VP_LINE_EVID_MTR_CMP	All FXS		71
VP_LINE_EVID_MTR_ABORT All FXS			71
VP_LINE_EVID_MTR_CAD	VCP, VE792	FXS	71
VP_LINE_EVID_MTR_ROLLOVER	VCP2-792, VE792	FXS	72
VP_LINE_EVID_CID_DATA All FXS			72
VP_LINE_EVID_RING_CAD All FXS			73
VP_LINE_EVID_SIGNAL_CMP All All			73
VP_LINE_EVID_TONE_CAD All All			73
VP_LINE_EVID_GEN_TIMER VCP2-792, VE792, MeLT All			74
VP_LINE_EVID_USER	VCP2-792, VE792	All	74

5.2.1 Event Specificity

Some event are device-specific, and some events are line-specific. The names of device-specific events generally begin with VP_DEV_EVID_, while the names of line-specific events generally begin with VP_LINE_EVID_.

VpGetEvent() sets some fields in the VpEventType struct according to the event specificity:

Table 5-2 VpEventType Fields Indicating Specificity

Event Specificity	Field Value
Line-specific	pLineCtx Valid pointer to the Line Context for the line associated with the event
	lineId	The line ID (previously assigned with vp Map Line Id()) for the line associated with the event
	channelId The hardware channel ID for the line associated with the event
Device-specific	pLineCtx VP_NULL
	lineId (not defined)
	channelId (not defined)

The deviceId and pDevCtx fields are always set to indicate the device on which the event occurred, regardless of specificity.

5.3 FAULT EVENTS

The fault events report critical VTD errors. The set of valid fault events is defined in the software by the VpFaultEventType enumeration.

5.3.1 VP\_DEV\_EVID\_BAT\_FLT

DESCRIPTION This event occurs when a battery fault is detected or is no longer detected. Refer to the appropriate Chip Set User's Guide for details on the battery fault condition.

T.S. OR HANDLE N/A

EVENT DATA Event data indicates the source of the battery fault and can be any of the values shown below, or multiple values ORed together. See Battery Name Interpretation, on page 66 for battery mapping.

Enumeration Data Type: VpBatFltEventDataType:
VP_BAT_FLT_NONE = 0x00 /* No battery fault */
VP_BAT_FLT_BAT1 = 0x02 /* Battery 1 fault */
VP_BAT_FLT_BAT2 = 0x01 /* Battery 2 fault */
VP_BAT_FLT_BAT3 = 0x04 /* Battery 3 fault */ 

RESULTS N/A

DEVICES All

TERMINATIONS All

5.3.2 VP\_DEV\_EVID\_CLK\_FLT

DESCRIPTION This event occurs when a clock fault is detected or is no longer detected. Refer to the appropriate Chip Set User's Guide for details on the clock fault condition.

T.S. OR HANDLE N/A

EVENT DATA Event data bit 0 indicates whether the fault condition is present (1) or absent (0), as detected by the SLAC.

RESULTS N/A

DEVICES All

TERMINATIONS All

5.3.3 VP\_LINE\_EVID\_THERM\_FLT

DESCRIPTION This event occurs when a thermal fault is detected or is no longer detected. The line may be autonomously moved into the Disconnect state when this event occurs, depending on how the VP_DEVICE_OPTION_ID_CRITICAL_FLT option is configured (see Section 4.3.2). Refer to the appropriate Chip Set User's Guide for details on the thermal fault condition.

T.S. OR HANDLE N/A

EVENT DATA Event data bit 0 indicates whether the fault condition is present (1) or absent (0).

RESULTS N/A

DEVICES All

TERMINATIONS All

5.3.4 VP\_LINE\_EVID\_DC\_FLT

DESCRIPTION

This event occurs when a DC fault is detected or is no longer detected. The line may be autonomously moved into the Disconnect state when this event occurs, depending on how VP_DEVICE_OPTION_ID_CRITICAL_FLT is configured (see Section 4.3.2). Refer to the appropriate Chip Set User's Guide for details on the DC fault condition. As the fault current detector is polarity-sensitive, this event occurs when the fault voltage is more negative than the voltage produced by the SLIC drivers.

T.S. OR HANDLE N/A

EVENT DATA

Event data bit 0 indicates whether the fault condition is present (1) or absent (0).

RESULTS N/A

DEVICES VCP-790, VCP2, VE792, MeLT

TERMINATIONS All

5.3.5 VP\_LINE\_EVID\_AC\_FLT

DESCRIPTION

This event occurs when a AC fault is detected or is no longer detected. The line may be autonomously moved into the Disconnect state when this event occurs, depending on how VP_DEVICE_OPTION_ID_CRITICAL_FLT is configured (see Section 4.3.2). Refer to the appropriate Chip Set User's Guide for details on the AC fault condition.

T.S. OR HANDLE N/A

EVENT DATA

Event data bit 0 indicates whether the fault condition is present (1) or absent (0).

RESULTS N/A

DEVICES VCP-790, VCP2, VE792, MeLT

TERMINATIONS All

5.3.6 VP\_DEV\_EVID\_EVQ\_OFL\_FLT

DESCRIPTION

This event occurs when the VTD event queue overflows, which results from the host microprocessor failing to retrieve events in a timely manner.

T.S. OR HANDLE N/A

EVENT DATA N/A

RESULTS N/A

DEVICES VE792

TERMINATIONS All

5.3.7 VP\_DEV\_EVID\_WDT\_FLT

DESCRIPTION

This event occurs when the VTD internal watchdog timer expires, implying that the VTD firmware has hung.

T.S. OR HANDLE N/A

EVENT DATA N/A

RESULTS N/A

DEVICES VE792

TERMINATIONS All

5.3.8 VP\_DEV\_EVID\_SYSTEM\_FLT

DESCRIPTION

This event indicates that a device or chipset (combination of devices) fault was detected.

T.S. OR HANDLE N/A

EVENT DATA

Bits set in the eventdata are internal to the VE792 chipset, corresponding to one of several external or internal errors. If this event occurs, the customer should send the corresponding eventdata value to Microsemi support.

RESULTS N/A

DEVICES VCP2, VE792, MeLT

TERMINATIONS All

5.4 SIGNALING EVENTS

The signaling events report changes on an individual line. The set of valid signaling events is defined in the software by the VpSignalingEventType enumeration.

5.4.1 VP\_LINE\_EVID\_HOOK\_OFF

DESCRIPTION

The behavior of this event depends on whether pulse-digit decoding is enabled or disabled. See VP_DEVICE_OPTION_ID_PULSE, on page 31 and VP_OPTION_ID_PULSE, on page 44 for details.

If pulse-digit decoding is enabled: This event occurs when the VTD/VP-API-II determines that the line has become off-hook when it was previously on-hook for a duration longer than the pulsing break and hook flash intervals. In other words, this event does not occur during pulse dialing.

If pulse-digit decoding is disabled: This event occurs every time the VTD/VP-API-II detects the off-hook condition. This event is reported during pulse dialing and hook-switch flash.

T.S. OR HANDLE Time stamp

EVENT DATA N/A

RESULTS N/A

DEVICES All

TERMINATIONS All

5.4.2 VP\_LINE\_EVID\_HOOK\_ON

DESCRIPTION

The behavior of this event depends on whether pulse-digit decoding is enabled or disabled. See VP_DEVICE_OPTION_ID_PULSE, on page 31 and VP_OPTION_ID_PULSE, on page 44 for details.

If pulse-digit decoding is enabled: This event occurs when the VTD/VP-API-II determines that the line is on-hook beyond the pulse-digit break period and hook flash period. In other words, this event does not occur during pulse dialing or a hook-switch flash. The exception is when an invalid pulse train is detected and an on-hook occurs while monitoring the pulse train. In that case, only an on-hook event is generated rather than an invalid digit.

If pulse-digit decoding is disabled: This event occurs every time the VTD/VP-API-II detects the on-hook condition. This event is reported during pulse dialing and hook-switch flash.

T.S. OR HANDLE Time stamp

EVENT DATA N/A

RESULTS N/A

DEVICES All

TERMINATIONS All

5.4.3 VP\_LINE\_EVID\_GKEY\_DET

DESCRIPTION

This event occurs when the ground-key condition is detected, which is used in ground-start signaling. If the system does not support ground-start signaling, then this condition could indicate a DC fault on the line. As the fault detector is polarity-sensitive, it indicates the presence of a fault voltage more positive than the voltage produced by the SLIC drivers.

T.S. OR HANDLE Time stamp

EVENT DATA N/A

RESULTS N/A

DEVICES All

TERMINATIONS All

5.4.4 VP\_LINE\_EVID\_GKEY\_REL

DESCRIPTION

This event occurs when the ground-key condition is no longer detected (ground-key release).

T.S. OR HANDLE Time stamp

EVENT DATA N/A

RESULTS N/A

DEVICES All

TERMINATIONS All

5.4.5 VP\_LINE\_EVID\_FLASH

DESCRIPTION

This event indicates that a hook-switch flash was detected. This event only occurs if pulse-digit decoding is enabled via VpSetOption(). See VP_DEVICE_OPTION_ID_PULSE, on page 31 and VP_OPTION_ID_PULSE, on page 44 for details.

T.S. OR HANDLE Time stamp

EVENT DATA

If the pulse decoding parameters (VP_OPTION_ID_PULSE) are set such that breakMax > flashMin, then the eventdata field indicates whether the pulse qualifies as both a pulse digit "1" and a flash (VP_FLASH_AND_DIGIT1), or only qualifies as a flash (VP_FLASH_ONLY).

RESULTS N/A

DEVICES All

TERMINATIONS FXS

5.4.6 VP\_LINE\_EVID\_STARTPULSE

DESCRIPTION

This event occurs when the start of a pulse digit or flash has been detected. This is useful for determining when to turn-off dial tone at the start of dialing. This event only occurs if pulse-digit decoding is enabled via VpSetOption(). See VP_DEVICE_OPTION_ID_PULSE, on page 31 and VP_OPTION_ID_PULSE, on page 44 for details.

T.S. OR HANDLE Time stamp

EVENT DATA N/A

RESULTS N/A

DEVICES All

TERMINATIONS FXS

5.4.7 VP\_LINE\_EVID\_EXTD\_FLASH

DESCRIPTION

This event can only be generated if EXTENDED_FLASH_HOOK is set to #define in vp_api_cfg.h.

This event occurs when an extended flash hook has been detected. This is useful for determining detection of "new call" request (flash duration longer than "hook flash" but less than "on hook"). This event only occurs if enabled by a conditional compile and if pulse-digit decoding is enabled via VpSetOption(). See VP_DEVICE_OPTION_ID_PULSE, on page 31 and VP_OPTION_ID_PULSE, on page 44 for details.

T.S. OR HANDLE Time stamp

EVENT DATA N/A

RESULTS N/A

DEVICES VCP2-792, VE792

TERMINATIONS FXS

5.4.8 VP\_LINE\_EVID\_DTMF\_DIG

DESCRIPTION This event occurs at the beginning and end of DTMF digit detection.

T.S. OR HANDLE Time stamp

EVENT DATA

Event data bits 3 to 0 contain the received digit information, which can be decoded by comparing with the VpDigitType (see VpSetLineTone(), on page 92) enumeration constants. Bit 4 indicates whether this event corresponds to the start (1) or the end (0) of the DTMF digit.

RESULTS N/A

DEVICES All

TERMINATIONS FXS

5.4.9 VP\_LINE\_EVID\_PULSE\_DIG

DESCRIPTION This event occurs when a pulse digit is detected.

T.S. OR HANDLE N/A

EVENT DATA

Event data bits 3 to 0 contain the received digit information, which can be decoded by comparing with the VpDigitType enumeration constants. Event data will be VP_DIG_NONE if while monitoring the pulse train, any digit fails to meet the breakMin, breakMax, makeMin, makeMax, or if an on-hook occurs within the interDigitMin time specified by VP_DEVICE_OPTION_ID_PULSE. See VP_DEVICE_OPTION_ID_PULSE, on page 31 and VP_OPTION_ID_PULSE, on page 44 for details.

RESULTS N/A

DEVICES All

TERMINATIONS FXS

5.4.10 VP\_LINE\_EVID\_MTONE

DESCRIPTION This event occurs when a modem tone is detected.

T.S. OR HANDLE N/A

EVENT DATA N/A

RESULTS N/A

DEVICES All

TERMINATIONS All

5.4.11 VP\_DEV\_EVID\_TS\_ROLLOVER

DESCRIPTION

This event occurs when the VP-API-II time stamp counter rolls-over from 65535 to 0. Since this counter is incremented every 0.5 ms, it rolls-over every 32.768 seconds.

T.S. OR HANDLE N/A

EVENT DATA N/A

RESULTS N/A

DEVICES All

TERMINATIONS All

5.4.12 VP\_LINE\_EVID\_HOOK\_PREQUAL

DESCRIPTION

This event occurs (with eventdata = VP_HOOK_PREQUAL_START) when an off-hook is detected on a line that has been configured with VP_OPTION_ID_PULSE parameters and offHookMin is set >0. It is normally followed by a VP_LINE_EVID_HOOK_OFF event after the hook qualification interval (offHookMin) expires.

If the phone goes back on-hook before the hook qualification interval expires, another VP_LINE_EVID_HOOK_PREQUAL event occurs, with eventdata = VP_HOOK_PREQUAL_ABORT. In this case, no VP_LINE_EVID_HOOK_ON event will be reported.

T.S. OR HANDLE Time stamp

EVENT DATA

Event data indicates whether the phone went off-hook or on-hook.

Enumeration Data Type: VpHookPrequalEventDataType:
VP_HOOK_PREQUAL_START = 0x00 /* Off-hook detected */
VP_HOOK_PREQUAL_ABORT = 0x01 /* On-hook detected */ 

RESULTS N/A

DEVICES VCP2-792, VE792

TERMINATIONS FXS

5.5 RESPONSE EVENTS

The response events occur as a result of some action initiated by the application. Several of these events have extended results data associated with them. The set of valid response events is defined in the software by the VpResponseEventType enumeration.

5.5.1 VP\_LINE\_EVID\_LLCMD\_TX\_CMP

DESCRIPTION

This event occurs after a low-level write command is issued to a device. Refer to for information on issuing low-level commands.

T.S. OR HANDLE N/A

EVENT DATA N/A

RESULTS N/A

DEVICES All

TERMINATIONS All

5.5.2 VP\_LINE\_EVID\_LLCMD\_RX\_CMP

DESCRIPTION

This event occurs after a low-level read command is issued to a device and the resulting data is available. Refer to for information on issuing low-level commands.

This event is non-maskable.

T.S. OR HANDLE Handle

EVENT DATA N/A

RESULTS

The application must call VpGetResults() with a pointer to a byte (uint8) buffer into which the resulting data is copied. The application is responsible for allocating enough storage for the data string and is responsible for interpreting the data.

The data is an array of 16-bit words. Regardless of the endianness of the host processor, the data will be stored in big-endian format. On little-endian systems, the data should be byte-swapped before processing.

DEVICES All

TERMINATIONS All

5.5.3 VP\_DEV\_EVID\_DNSTR\_MBOX

DESCRIPTION

This event occurs after the VTD has emptied the downstream mailbox, indicating that the application can call another VP-API-II function that uses the downstream mailbox. Instead of using this event, it is generally easier for the application to repeatedly call (poll) any VP-API-II function that uses the downstream mailbox until the VP_STATUS_MAILBOX_BUSY result is not returned. The VP-API-II can be configured to do this polling automatically. See VP792_MAILBOX_SPINWAIT in vp_api_cfg.h for details.

T.S. OR HANDLE N/A

EVENT DATA N/A

RESULTS N/A

DEVICES All

TERMINATIONS All

5.5.4 VP\_LINE\_EVID\_RD\_OPTION

DESCRIPTION

This event occurs as a result of calling VpGetOption() and indicates that the VP-API-II has retrieved the requested option setting from the VTD. See VpGetOption(), on page 112 for information on that function.

This event is non-maskable.

T.S. OR HANDLE Handle

EVENT DATA

Event data is of VpOptionIdType type and indicates which option was read from the VTD, allowing the application to correctly interpret the associated results data. See Option Summary. on page 29 for the complete list of VP-API-II options.

RESULTS

The data type of the result associated with this event depends on exactly which option was read. The application should determine the option data type by inspecting the event data field, allocate a buffer of the appropriate type, and call VpGetResults() with a pointer to that buffer. Chapter 4 describes the result type for each VP-API-II option.

DEVICES All

TERMINATIONS All

5.5.5 VP\_LINE\_EVID\_RD\_LOOP

DESCRIPTION

The event occurs as a result of calling VpGetLoopCond() and indicates that the loop condition results are available. See VpGetLoopCond(). on page 111 for information on that function.

This event is non-maskable.

T.S. OR HANDLE Handle

EVENT DATA N/A

RESULTS

The results associated with this event are passed through the VpLoopCondResultstype structure shown below.

typedef struct {
    int16 rloop; /* Measured loop resistance */
    int16 ilg; /* Sensed longitudinal (common mode) current */
    int16 imt; /* Sensed metallic (differential) current */
    int16 vsab; /* Sensed voltage on AB (tip/ring) leads */
    int16 vbat1; /* Battery 1 measured voltage */
    int16 vbat2; /* Battery 2 measured voltage */
    int16 vbat3; /* Battery 3 measured voltage */
    int16 mspl; /* Measured metering signal peak level */
    VpBatteryType selectedBat; /* Battery currently used for DC feed */
    VpDcFeedRegionType dcFeedReg; /* DC feed region presently selected */
} VpLoopCondResultsType;

Enumeration Data Type: VpBatteryType:
    VP_BATTERY_UNDEFINED /* Not known or feature not supported */
    VP_BATTERY_1 /* Battery 1 */
    VP_BATTERY_2 /* Battery 2 */
    VP_BATTERY_3 /* Battery 3 */

Enumeration Data Type: VpDcFeedRegionType:
    VP_DF_UNDEFINED /* Not known or feature not supported */
    VP_DF_ANTI_SAT_REG /* DC feed is in anti saturation region */
    VP_DF_CNST_CUR_REG /* DC feed is in constant current region */
    VP_DF_RES_FEED_REG /* DC feed is in resistive feed region */ 

The application can convert the integer results in this structure to real-world values using the conversion equations found in the following tables. Note that these equations assume that the application is using the recommended external components. Refer to the appropriate Microsemi documentation (Chip Set User's Guide or Data Sheet) for recommended application circuits.

Table 5-3 Loop Condition Results Conversion: 792

Loop Condition VE792
Loop Resistance	rloop x 1.0 Ω
Longitudinal Current	(ilg / 32768) x 100.0 mA
Metallic Current	(imt / 32768) x 100.0 mA
Metallic Voltage	(vsab / 32768) x 400.0 V
Battery N Voltage	(vbatN / 32768) x 200 V
Metering Signal Peak Current	(mspl / 32768) x 41.11 mA_peak @ 12KHz(mspl / 32768) x 43.74 mA_peak @ 16KHz

These results are based on a single instantaneous reading; no filtering is performed. The ilg value will fluctuate under the presence of AC induction on the line.

The loop resistance (rloop) result is not valid in the following states: VP_LINE_STANDBY, VP_LINE_STANDBY_POLREV, VP_LINE_TIP_OPEN, VP_LINE_RING_OPEN, VP_LINE_DISCONNECT, VP_LINE_RINGING, VP_LINE_RINGING_POLREV, and VP_LINE_DISABLED.

The longitudinal (ilg) and metallic (imt) current results are not valid in the following states: VP_LINE_DISCONNECT, VP_LINE_RINGING, VP_LINE_RINGING_POLREV, and VP_LINE_DISABLED.

The metallic (imt) current result is not valid in the following states: VP_LINE_TIP_OPEN and VP_LINE_RING_OPEN.

The metallic voltage (vsab) result is not valid in the following states: VP_LINE_STANDBY, VP_LINE_TIP_OPEN, VP_LINE_RING_OPEN, VP_LINE_DISCONNECT, and VP_LINE_PARK.

If the loop conditions measurement is taken during a metering pulse, the mspl field reports the current metering signal peak current. Otherwise, the mspl field reports the peak current of the previous metering signal.

VpLoopCondResultsType returns the measured battery voltages using the generic battery names vbat1, vbat2, and vbat3. Table 5-4 decodes these generic battery names to device-specific battery names (VBH, VBL, etc.). Note that the interpretation of vBat1 and vBat2 depends on how the device's sense pins are connected to the battery supplies as shown in Table 5-4.

Table 5-4 Battery Name Interpretation

Device Type	Normal Config. Crossed Config.				vBat3vBat1 vBa
VE792 VBL VBH	n/a	n/a	VBP

The selectedBat and dcFeedReg results are just enumeration types and require no conversion.

DEVICES All

TERMINATIONS All

5.5.6 VP\_EVID\_CAL\_CMP

DESCRIPTION

This event occurs as a result of calling VpCalCodec() or VpCalLine() and indicates that the requested device or line is calibrated. In the case of a codec calibration, the line number returned with this event is the lowest-numbered line controlled by the target SLAC device. Note that disabling (masking) this event blocks this event for both the VpCalCodec() and VpCalLine() functions. See VpCalCodec(), on page 81 or VpCalLine(), on page 82 for information on these functions.

T.S. OR HANDLE N/A

EVENT DATA N/A

RESULTS N/A

DEVICES All

TERMINATIONS All

5.5.7 VP\_EVID\_CAL\_BUSY

DESCRIPTION

This event occurs as a result of calling VpCalCodec() or VpCalLine() and indicates that the requested device or line can not be calibrated at this time. In the case of a codec calibration, the line number returned with this event is the lowest-numbered line controlled by the target SLAC device. Note that disabling (masking) this event blocks this event for both the VpCalCodec() and VpCalLine() functions. See VpCalCodec(), on page 81 or VpCalLine(), on page 82 for information on these functions.

T.S. OR HANDLE N/A

EVENT DATA N/A

RESULTS N/A

DEVICES All

TERMINATIONS All

5.5.8 VP\_LINE\_EVID\_GAIN\_CMP

DESCRIPTION

This event occurs as a result of calling VpSetRelGain() and indicates that the transmit and/or receive gain is adjusted. See VpSetRelGain(). on page 94 for information on that function.

If the event is masked, the results will not be placed in the response mailbox, so VpGetResults() should not be called.

T.S. OR HANDLE Handle

EVENT DATA N/A

RESULTS

Gain adjustment results are returned through the VpRelGainResultsType structure defined below.

typedef struct {
    VpGainResultType gResult; /* Success / Failure status return */
    uint16 gxValue; /* new GX register value */
    uint16 grValue; /* new GR register value */
    VpRelGainResultsType; 

The gResult variable indicates whether overflow occurred in the calculation of the transmit or receive gain. If an error does occur, the corresponding gain is automatically restored to the default value from the AC Profile. gResult can have any of the following values:

Enumeration Data Type: VpGainResultType:
VP_GAIN_SUCCESS /* Gain setting adjusted successfully */
VP_GAIN_GR_OOR /* Receive gain overflow, reset to default */
VP_GAIN_GX_OOR /* Transmit gain overflow, reset to default */
VP_GAIN_BOTH_OOR /* Tx and Rx gain overflow, reset to default */ 

The gxValue and grValue variables return the contents of the VTD gain registers.

DEVICES All

TERMINATIONS

All

5.5.9 VP\_DEV\_EVID\_DEV\_INIT\_CMP

DESCRIPTION

This event occurs as a result of calling VpInitDevice() and indicates that VTD initialization is done. See VpInitDevice(). on page 77 for information on that function.

This event is non-maskable.

T.S. OR HANDLE N/A

EVENT DATA N/A

RESULTS N/A

DEVICES All

TERMINATIONS

All

5.5.10 VP\_LINE\_EVID\_LINE\_INIT\_CMP

DESCRIPTION

This event occurs as a result of calling VpInitLine() and indicates that the requested line is initialized. See VpInitLine(), on page 79 for information on that function.

This event is non-maskable.

T.S. OR HANDLE N/A

EVENT DATA N/A

RESULTS N/A

DEVICES All

TERMINATIONS All

5.5.11 VP\_DEV\_EVID\_IO\_ACCESS\_CMP

DESCRIPTION

This event occurs as a result of calling VpDeviceIoAccessExt() and indicates that the requested I/O access is done. See VpDeviceIoAccessExt(), on page 103 for information.

This event is non-maskable.

T.S. OR HANDLE N/A

EVENT DATA

The event data variable indicates whether the operation was a read (VP_DEVICE_IO_READ) or write (VP_DEVICE_IO_WRITE).

RESULTS

If this event corresponds to an I/O read operation, the application should call VpGetResults() with a pointer to an appropriate struct -- a VpDeviceIoAccessExtType struct should be passed. See VpDeviceIoAccessExt(). on page 103 for a description of this struct.

DEVICES All

TERMINATIONS All

5.5.12 VP\_LINE\_EVID\_LINE\_IO\_RD\_CMP

DESCRIPTION

This event occurs as a result of calling VpLineloAccess() with direction = VP_IO_READ and indicates that the requested operation is complete. See VpLineloAccess(), on page 102 for information on this function.

This event is non-maskable.

T.S. OR HANDLE Handle

EVENT DATA N/A

RESULTS

The application should call VpGetResults() with a pointer to a VpLineIoAccessType struct to receive the results associated with this event. See VpLineloAccess(), on page 102 for a description of this struct.

DEVICES VCP2, VE792, MeLT-VCP

TERMINATIONS All

5.5.13 VP\_LINE\_EVID\_LINE\_IO\_WR\_CMP

DESCRIPTION

This event occurs as a result of calling VpLineloAccess() with direction = VP_IO_WRITE and indicates that the requested operation is complete. See VpLineloAccess(), on page 102 for information on this function.

T.S. OR HANDLE Handle

EVENT DATA N/A

RESULTS N/A

DEVICES VCP2, VE792, MeLT-VCP

TERMINATIONS All

5.5.14 VP\_LINE\_EVID\_QUERY\_CMP

DESCRIPTION

This event occurs as a result of calling VpQuery() and indicates that the requested operation is complete.

This event is non-maskable.

T.S. OR HANDLE Handle

EVENT DATA N/A

RESULTS

The application should call VpGetResults() with a pointer to an instance of VpQueryResultsType specified below:

typedef union {
    int16 temp;
    uint16 meterCount;
    uint16 rLoop;
} VpQueryResultsType; 

Table 5-5 VpQuery Value Interpretation

VpQueryResultsType conversion
VP_QUERY_ID_TEMPERATURE	temperature( ^0C ) = (temp/ 2^15 )* 286.834 + 152.976
VP_QUERY_ID_METER_COUNT	number of metering pulses = meterCount
VP_QUERY_ID_LOOP_RES	loop resistance( ) = rLoop

DEVICES VCP2-792, VE792, MeLT

TERMINATIONS All

5.6 TEST EVENTS

The test events occur as a result of the application calling a VP-API-II line-test or self-test function. The set of valid test events is defined in the software by the VpTestEventType enumeration.

5.6.1 VP\_LINE\_EVID\_TEST\_CMP

DESCRIPTION

This event occurs as a result of calling VpTestLine() and indicates that the requested test is done. This event also occurs when certain VP-API-II functions, such as VpInitDevice() and VpCallLine(), force a test to abort. Refer to Chapter 9 for a complete discussion of the VP-API-II testing facilities.

This event is non-maskable.

T.S. OR HANDLE N/A

EVENT DATA N/A

RESULTS

VpTestLine() serves as the single entry point for many different VP-API-II line tests. The top-level result type for all tests that generate this event is the same regardless of which test is executed. This test result type, named VpTestResultType, is described in Chapter 9. The application should allocate a buffer of VpTestResultType type and call VpGetResults() with a pointer to that buffer. VpTestResultType contains a C union, which is used to merge the different individual test result types into a single structure. Chapter 9 covers the individual test result types in detail.

DEVICES All

TERMINATIONS All

5.6.2 VP\_LINE\_EVID\_DTONE\_DET

DESCRIPTION

This event occurs while running a dial tone test using VpTestLine(). The API raises this event at the start of dial tone detection. The exact conditions for dial tone detection are discussed in VP_TEST_ID_DIALTONE, on page 138.

T.S. OR HANDLE N/A

EVENT DATA

Event data contains the sample count at the time of detection. The sample count is reset at the start of the dial tone test and increments at an 8KHz rate (every 125 s).

RESULTS N/A

DEVICES All

TERMINATIONS FXS

5.6.3 VP\_LINE\_EVID\_DTONE\_LOSS

DESCRIPTION

This event occurs while running a dial tone test using VpTestLine(). The API raises this event at the end of dial tone detection. The exact conditions for dial tone detection are discussed in VP_TEST_ID_DIALTONE, on page 138.

T.S. OR HANDLE N/A

EVENT DATA

Event data contains the sample count at the time of detection loss. The sample count is reset at the start of the dial tone test and increments at an 8KHz rate (every 125 s).

RESULTS N/A

DEVICES All

TERMINATIONS FXS

5.7 PROCESS EVENTS

The process events report the progress of some process initiated by the application. The set of valid process events is defined in the software by the VpProcessEventType enumeration.

5.7.1 VP\_LINE\_EVID\_MTR\_CMP

DESCRIPTION

This event occurs as a result of calling VpStartMeter32Q() and indicates that the metering signal was generated as requested.

T.S. OR HANDLE N/A

EVENT DATA This field contains the number of complete metering pulses transmitted.

RESULTS N/A

DEVICES All

TERMINATIONS FXS

5.7.2 VP\_LINE\_EVID\_MTR\_ABORT

DESCRIPTION

This event occurs as a result of calling VpStartMeter32Q() and indicates that the metering signal was aborted before completion.

T.S. OR HANDLE N/A

EVENT DATA

This field contains the number of complete metering pulses transmitted. If a pulse was interrupted it is not included in this count.

RESULTS N/A

DEVICES All

TERMINATIONS FXS

5.7.3 VP\_LINE\_EVID\_MTR\_CAD

DESCRIPTION

This event occurs as a result of calling VpStartMeter32Q() and indicates that number of metering pulses that have been sent so far. When using VpStartMeter32Q(), this event is generated (if unmasked) after every eventRate ON periods of the metering signal, until the specified metering sequence is complete.

T.S. OR HANDLE N/A

EVENT DATA This field contains the number of complete metering pulses transmitted.

RESULTS N/A

DEVICES VCP, VE792

TERMINATIONS FXS

5.7.4 VP\_LINE\_EVID\_MTR\_ROLLOVER

DESCRIPTION

This event occurs as a result of calling VpStartMeter32Q() and indicates that the maximum number of metering pulses (65535) was generated. This condition is possible if the application specifies "infinite" number of pulses (onTime != 0; numMeters = 0). Note that metering pulses will continue be generated after issuing this event, but the pulse counter will restart at a value of 1.

T.S. OR HANDLE N/A

EVENT DATA N/A

RESULTS N/A

DEVICES VCP2-792, VE792

TERMINATIONS FXS

5.7.5 VP\_LINE\_EVID\_CID\_DATA

DESCRIPTION

This event indicates that the Caller ID data buffer is either half-empty or empty, depending on the state of the flag attached to the event. This event occurs as a result of calling VpInitCid(), VpSendCid(), or VpContinueCid().

T.S. OR HANDLE N/A

EVENT DATA

The event data variable indicates whether the VTD can take more Caller ID data or Caller ID transmission is done. It can have the following values:

Enumeration Data Type: VpCidDataEventType:
VP_CID_DATA_NEED_MORE_DATA /* Caller ID is expecting more data */
VP_CID_DATA_TX_DONE /* Caller ID transmission is complete */ 

The VP_CID_DATA_NEED_MORE_DATA event occurs when the Caller ID data buffer has 16 bytes left to transmit. The application can load up to 16 more bytes of Caller ID data into the buffer when this event occurs.

The VP_CID_DATA_TX_DONE event occurs after the VTD transmits the last byte of Caller ID data and completes the Caller ID sequence. This event also occurs for any other condition that causes CID to terminate abnormally (e.g., off-hook, no ack from CPE for type II CID, etc.).

RESULTS N/A

DEVICES All

TERMINATIONS FXS

5.7.6 VP\_LINE\_EVID\_RING\_CAD

DESCRIPTION

This event occurs when the VP-API-II/VTD performs automatic ringing cadencing. It notifies the application of ringing-on and ringing-off state transitions as the VP-API-II/VTD executes the specified cadence. This event does not occur for any line that does not have a ringing cadence applied to it. See VpInitRing(). on page 83 for information on applying a ringing cadence to a line. This event also does not occur when the ringing cadence is halted because of a state change or ring-trip.

T.S. OR HANDLE N/A

EVENT DATA

Event data contains a value of VpRingCadEventType type, which indicates the type of ringing cadence state change that occurred.

Enumeration Data Type: VpRingCadEventType:
VP_RING_CAD_BREAK, /* Begin OFF period of ringing cadence */
VP_RING_CAD_MAKE, /* Begin ON period of ringing cadence */
VP_RING_CAD_DONE, /* End of ringing cadence */ 

RESULTS N/A

DEVICES All

TERMINATIONS FXS

5.7.7 VP\_LINE\_EVID\_SIGNAL\_CMP

DESCRIPTION

This event occurs as a result of calling VpSendSignal() and indicates that the requested signal was sent. See VpSendSignal(), on page 95 for information on that function.

T.S. OR HANDLE N/A.

EVENT DATA

Event data contains a variable of VpSendSignalType type, which indicates the type of signal that was sent. This enumeration type is described with VpSendSignal(). on page 95.

RESULTS N/A

DEVICES All

TERMINATIONS All

5.7.8 VP\_LINE\_EVID\_TONE\_CAD

DESCRIPTION

This event occurs when the VP-API-II/VTD performs tone cadencing. It notifies the application of completion of the cadence. Completion of the cadence occurs when a cadence reaches an "always on", "always off", or end of cadence.

T.S. OR HANDLE N/A

EVENT DATA N/A

RESULTS N/A

DEVICES All

TERMINATIONS All

5.7.9 VP\_LINE\_EVID\_GEN\_TIMER

DESCRIPTION This event is generated in a response to VpGenTimerCtrl()

This event is not maskable.

T.S. OR HANDLE Handle

EVENT DATA Contains one of the following values:

VP_GEN_TIMER_STATUS_CMP    /* Timer expired successfully */
VP_GEN_TIMER_STATUS_CANCELED    /* Timer canceled successfully */
VP_GEN_TIMER_STATUS_RESRC_NA    /* Tried to start a new timer, but failed due to all timer resources in use */
VP_GEN_TIMER_STATUS_UNKNOWN    /* Tried to cancel a timer, but specified an unknown handle/line combination. */ 

RESULTS N/A

DEVICES VCP2-792, VE792, MeLT

TERMINATIONS All

5.7.10 VP\_LINE\_EVID\_USER

DESCRIPTION

Using Profile Wizard, a special User Event command can be embedded in a tone cadence or ringing cadence profile. When the cadence is executed using VpSetLineTone() or VpSetLineState(), the sequencer will generate a VP_LINE_EVID_USER event upon reaching the User Event command.

T.S. OR HANDLE N/A

EVENT DATA

Using Profile Wizard, the event data can be specified as any value from 0 to 7.

RESULTS N/A

DEVICES VCP2-792, VE792

TERMINATIONS All

6 INITIALIZATION FUNCTIONS

6.1 OVERVIEW

This chapter discusses VP-API-II functions that perform initialization. These functions are summarized below.

• VpInitDevice() – Initializes all lines of a device and applies the specified profiles to those lines.
• VpInitLine() – Initializes an individual FXS line and applies the specified profiles to that line.
• VpConfigLine() – Sets the AC, DC, and Ringing Profiles for an individual line.
• VpCalCodec() – Calibrates internal SLAC level parameters.
• VpCalLine() – Calibrates internal line level parameters.
• VpInitRing() – Sets the ringing parameters such as the ringing cadence and Caller ID profile for an individual line.
• VpInitCid() – Prepares a line for a Caller ID ring sequence.
• VpInitMeter() – Configures the metering signal generator of an individual line.
• VpInitProfile() – Initializes the device's profile tables.
• VpSetBatteries() – Sets the battery settings in the device, used to improve dc feed performance on devices that support this function.

6.2 FUNCTION DESCRIPTIONS

6.2.1 VpInitDevice()

SYNTAX vpStatusType

VpInitDevice(
    VpDevCtxType *pDevCtx, /* Pointer to device context */
    VpProfilePtrType pDevProfile, /* Pointer to Device profile */
    VpProfilePtrType pAcProfile, /* Pointer to AC profile */
    VpProfilePtrType pDcProfile, /* Pointer to DC profile */
    VpProfilePtrType pRingProfile, /* Pointer to ringing profile */
    VpProfilePtrType pFxoAcProfile, /* Reserved */
    VpProfilePtrType pFxoCfgProfile)    /* Reserved */ 

DESCRIPTION

This function initializes all lines controlled by the VTD associated with the passed device context. This includes performing the recommended power-up sequence specified in the device's Chip Set User's Guide, including executing VpCalCodec() for each line, and setting all options (device and line) to their default values.

This function should be called after creating the device and line objects via

VpMakeDeviceObject() and VpMakeLineObject(), respectively. All device and line options are overwritten with their default values as a result of calling this function. The application should not change device or line options until the initialization procedure is complete, as indicated by the VP_DEV_EVID_DEV_INIT_CMP event.

The pDevProfile parameter takes a pointer to a Device Profile and is required. This function returns an error code if pDevProfile does not point to a valid profile.

The VTD requires parameters for operation that may include AC characteristics, DC feed options, and ringing parameters. The pAcProfile, pDcProfile, and pRingProfile arguments of this function provide the required parameters. If these parameters are set to VP_PTABLE_NULL, then compiled-in defaults will be used. The pFxoAcProfile and pFxoCfgProfile arguments are reserved and should always be set to VP_PTABLE_NULL.

The profile types accepted by this function are described in Profile Types, on page 13. For each of these profiles, the application can supply either a pointer to a valid profile or a profile table index. Valid profiles must be loaded into the profile table before a profile table index can be used. See Profiles, on page 13.

Upon completion of this function, all initialized lines are placed in the VP_LINE_DISCONNECT line state.

The following relay states (based on termination type) are applied at the completion of VpInitDevice().

FXS Line Termination Type Relay State

VP_TERM_FXS_GENERIC VP_RELAY_NORMAL
VP_TERM_FXS_TI    VP_RELAY_NORMAL
VP_TERM_FXS_RR    VP_RELAY_NORMAL
VP_TERM_FXS_RR_MW    VP_RELAY_NORMAL
VP_TERM_FXS_RR_TI    VP_RELAY_NORMAL 

Notes:

1. The application must provide a valid pDevProfile for device initialization to occur. Otherwise, an error is returned.
2. The application may provide VP_PTABLE_NULL pointer for any profiles in this function (except the Device Profile), then later use VpInitLine() or VpConfigLine() as needed to apply specific profiles to specific lines.
3. Only lines that have previously been created and associated with the device using VpMakeLineObject() will be initialized at the time this function is called.
4. Line behavior is not guaranteed when initializing a line with a VP_PTABLE_NULL pointer.
5. This function forces any line that is currently in Test Mode immediately out of Test Mode. A VP_LINE_EVID_TEST_CMP event is generated, and VP_TEST_STATUS_ABORTED is returned through the errorCode field of the vpTestResultType structure.

See VP-API-II Function Return Type, on page 10

EVENTS

GENERATED

VP_DEV_EVID_DEV_INIT_CMP, on page 67

DEVICES All

TERMINATIONS All

6.2.2 VplInitLine()

SYNTAX vpStatusType

VpInitLine(

VpLineCtxType *pLineCtx, /* Pointer to line context */

VpProfilePtrType pAcProfile, /* Pointer to AC profile */

VpProfilePtrType

pDcFeedOrFxoCfgProfile,

/* Ptr to DC profile */

VpProfilePtrType

pRingProfile)

/* Pointer to ringing profile */

DESCRIPTION

This function is the line level equivalent to VpInitDevice(). It resets all line parameters and options to their default values, loads the provided profile data (if any) to the line, and resets the line and relay state according to the list in VpInitDevice(). Similar to VpInitDevice(), line specific behavior is not guaranteed if profiles are not provided. This function also executes VpCallLine().

Notes:

1. If the line is currently performing Caller ID transmission, metering, or ringing, all such processes are stopped. No events are reported as a consequence of aborting these processes.

RETURNS

See VP-API-II Function Return Type, on page 10

EVENTS

GENERATED

VP LINE EVID LINE INIT CMP, on page 68

DEVICES VE792, VCP

TERMINATIONS All

6.2.3 VpConfigLine()

SYNTAX vpStatusType

VpConfigLine(

VpLineCtxType *pLineCtx, /* Pointer to line context */

VpProfilePtrType pAcProfile, /* Pointer to AC profile */

VpProfilePtrType

pDcFeedOrFxoCfgProfile,

/* Ptr to DC feed profile */

VpProfilePtrType

pRingProfile)

/* Pointer to ringing profile */

DESCRIPTION

This function re-initializes the specified line's AC, DC, and ringing parameters with the profiles provided by the function's arguments. Unlike VpInitLine() or VpInitDevice(), this function does not reset the line or the device; it merely loads the given profiles. This function is useful for applying unique profiles to a particular line.

This function uses profiles in the same manner as VpInitDevice(). on page 77. See Chapter 2, on page 13 for a complete description of the profiles.

Any profile pointer argument equal to VP_PTABLE_NULL is ignored and the line's configuration is unchanged in regard to that profile.

Notes:

In most cases, it is necessary to call vpCalLine() after calling this function only if changing DC or Ringing profiles.

RETURNS

See VP-API-II Function Return Type, on page 10

EVENTS

GENERATED

None

DEVICES All

TERMINATIONS All

6.2.4 VpCalCodec()

SYNTAX vpStatusType

VpCalCodec(

VpLineCtxType *pLineCtx, /* Pointer to line context */

VpDeviceCalType mode) /* Sets the calibration mode */

DESCRIPTION

This function affects the entire SLAC (the SLAC associated with the line context passed), so all lines controlled by the same SLAC should be removed from service before running VpCalCodec(). This function calibrates all lines serviced from the SLAC and also calibrates the battery sense circuit.

The policy followed when performing a calibration is given by the mode argument, which can be one of the following enumerated values:

Enumeration Data Type: VpDeviceCalType: VP_DEV_CAL_NOW /* Calibrate immediately */ VP_DEV_CAL_NBUSY /* Calibrate if all lines are "on-hook" */

If VP_DEV_CAL_NOW is specified, then the device is halted immediately and calibration started regardless of the state of each line.

If VP_DEV_CAL_NBUSY is specified, then the device will run calibration only if all lines of the device are in a state that would not conflict with calibration. If calibration cannot complete due to a line or device conflict, the event VP_EVID_CAL_BUSY is returned and no calibration is performed.

VpCalCodec() can always run with condition VP_DEV_CAL_NBUSY if all lines are set to VP_LINE_DISCONNECT prior to running calibration.

When calibration is done each line is left in the state the line was in prior to running VpCalCodec().

Notes:

1. Calibration is automatically performed for a given device during the VpInitDevice() function.
2. No other API-II functions that will configure or control the device or line should be called by the application after calling VpCalCodec() until the resulting event is received.

RETURNS

See VP-API-II Function Return Type, on page 10

EVENTS

VP EVID CAL CMP, on page 66

GENERATED

VP EVID CAL BUSY, on page 66

DEVICES All

TERMINATIONS All

6.2.5 VpCalLine()

SYNTAX vpStatusType

VpCalLine(

VpLineCtxType *pLineCtx) /* Pointer to line context */

DESCRIPTION

This function is the channel-specific equivalent of VpCalCodec(); only the specified line is calibrated. The other lines need not be taken out of service and the battery sense circuit is not calibrated.

The VP_EVID_CAL_BUSY event occurs if for any reason VpCalLine() cannot be performed, otherwise the VP_EVID_CAL_CMP event is returned when calibration is done.

Notes:

1. No other API-II function that will configure or control the line should be called by the application after calling VpCalLine() until the resulting event is received.

RETURNS

See VP-API-II Function Return Type, on page 10

EVENTS

VP EVID CAL CMP, on page 66

GENERATED

VP EVID CAL BUSY, on page 66

DEVICES All

TERMINATIONS All

6.2.6 VpInitRing()

SYNTAX vpStatusType

VpInitRing(

VpLineCtxType *pLineCtx, /* Pointer to line context */

VpProfilePtrType pCadProfile,

/* Pointer to ringing cadence profile */

VpProfilePtrType pCidProfile)

/* Pointer to Caller ID profile */

DESCRIPTION

VpInitRing() initializes Ringing state parameters for the line associated with pLineCtx. These parameters determine the ringing cadence and Caller ID Profile to be used while the line is in the VP_LINE_RINGING state.

The Caller ID behavior and the Cadence employed during the Ringing state are defined by profiles. Like other profiles, the ringing profiles used by this function may be pre-loaded in the profile tables or can be directly loaded from application memory. Refer to Profile Tables, on page 14 for more information.

The pCadProfile argument selects the profile to be used for the ringing cadence. If pCadProfile is VP_PTABLE_NULL, then the default "always on" ringing cadence is used.

The pCidProfile argument determines which Caller ID Profile is used during the ringing cadence. This function should be called with a Caller ID Profile when implementing Ringing related Caller ID, normally referred to as "Type-I". If pCidProfile is a valid profile table index or profile pointer (not VP_PTABLE_NULL) and the ringing cadence includes Caller ID transmission, then Caller ID data is transmitted during subsequent ringing cadences on this line. Caller ID events (VP_LINE_EVID_CID_DATA) also occur during these ringing cadences. If pCidProfile equals VP_PTABLE_NULL, then Caller ID data is not automatically transmitted during subsequent ringing cadences on this line. The application can still manually transmit Caller ID using the VpSendCid() function. See VpSendCid(). on page 96 for details.

If automatic Type-I Caller ID is enabled for a line, the application should call VpInitCid() to copy Caller ID data into the Caller ID transmit buffer before putting the line into the Ringing state. See VpInitCid(). on page 85 for more information.

Each line controlled by the VP-API-II defaults to internal ringing with an "always on" cadence and no Caller ID, if otherwise not initialized. If the defaults are not acceptable, then this function should be called at least once for each line before putting the lines into Ringing mode. It is only necessary to initialize each line once, usually after a system reset, unless different ringing parameters are needed per call, such as a unique ringing cadence.

This function does not start ringing on the line. The application must call VpSetLineState() with VP_LINE_RINGING as the state argument in order to actually start ringing the line. The line will continue ringing, with the cadence defined by pCadProfile, until VpSetLineState() is called with a non-ringing state argument or an off-hook is detected.

Notes:

1. Type-I Caller ID has the CLI (Caller Line Identity) frame transmitted as part of the caller alert sequence (ringing signal plus any other signals, such as Caller ID). This type of CLI is only transmitted while the line is on-hook. Different countries have different methods for performing Type-I Caller ID.

2. Type-II Caller ID is transmitted with the line off-hook, and provides caller line identity to lines with call waiting calls. Usually Type-II Caller ID requires a type of handshake with the CPE before FSK transmission begins.

RETURNS

See VP-API-II Function Return Type, on page 10

EVENTS

GENERATED

None

DEVICES VE792, VCP

TERMINATIONS All

6.2.7 VpInitCid()

SYNTAX vpStatusType

VpInitCid(

VpLineCtxType *pLineCtx, /* Pointer to line context */

uint8 length, /* Length of Caller ID data */

uint8p pCidData) /* Pointer to the Caller ID data */

DESCRIPTION

This function should be called before placing a line into the Ringing state if the associated line was set-up for Caller ID by VpInitRing(). If VpInitCid() is not called before the line is placed into Ringing, then the VTD will transmit a Caller ID message containing undefined data. Note that this function is necessary when implementing Caller ID Type-I.

The length argument should specify the total length in bytes of the entire message to be transmitted if the message length is less than or equal to 32 bytes, otherwise it should be set to 32. Since Caller ID messages can be longer than 32 bytes, the application may need to make several VP-API-II function calls to transmit a complete Caller ID message. To facilitate this, the VP-API-II generates the VP_LINE_EVID_CID_DATA event (with eventually equal to VP_CID_DATA_NEED_MORE_DATA) when 16 bytes of Caller ID data remain in the transmit buffer. It takes approximately 133 ms to send 16 bytes of CID data. Upon receiving this event, the application must call VpContinueCID() to buffer any remaining Caller ID data. If this function is called with length less than or equal to 16 bytes, then the VP-API-II assumes that the Caller ID message is not longer than 16 bytes and therefore does not generate the VP_CID_DATA_NEED_MORE_DATA event.

The pCidData argument should point to a buffer containing the initial bytes to be sent as the Caller ID message. Neither the VP-API-II nor the VTD automatically generate the message type or message length. These should be included, if desired, in the buffer pointed to by pCidData.

When the VTD is done transmitting Caller ID it generates the VP_LINE_EVID_CID_DATA event with eventData member set to VP_CID_DATA_TX_DONE.

RETURNS

See VP-API-II Function Return Type, on page 10

EVENTS

GENERATED

VP LINE EVID CID DATA, on page 72

DEVICES VE792, VCP

TERMINATIONS All

6.2.8 VpInitMeter()

SYNTAX vpStatusType

VpInitMeter(

VpLineCtxType *pLineCtx, /* Pointer to line context */

VpProfilePtrType pMeterProfile) /* Ptr to metering profile */

DESCRIPTION

This function initializes the metering parameters for the specified line, using the values contained in the Metering Profile. It should be called prior to initiating one or more metering pulses using VpStartMeter32Q().

Like other profiles, the metering profiles used by this function may be pre-loaded in the profile tables or can be directly loaded from application memory. Refer to Profile Tables, on page 14 for more information.

If pMeterProfile is VP_PTABLE_NULL, nothing happens and this function simply returns VP_STATUS_SUCCESS.

RETURNS

See VP-API-II Function Return Type, on page 10

EVENTS

None

GENERATED

DEVICES VE792, VCP

TERMINATIONS All

6.2.9 VpInitProfile()

SYNTAX vpStatusType

VpInitProfile(

VpDevCtxType *pDevCtx, /* Pointer to device context */

VpProfileType type, /* Type of profile to load */

VpProfilePtrType pProfileIndex, /* Profile index selector */

VpProfilePtrType pProfile) /* Pointer to the profile data */

DESCRIPTION

This function initializes an entry in the VTD profile table. This function copies the profile pointed to by pProfile into the API profile table. (If VP_COMMON_ADDRESS_SPACE is defined in vp_api_cfg.h, then this function merely saves the pointer, rather than copying the entire profile.) Once initialized by this function, this entry in the profile table may be accessed in subsequent VP-API-II function calls by specifying its index number. See Profile Tables, on page 14 for more information.

The default entries in the profile table may not contain valid profiles. Hence the application should initialize the profile table with valid profiles if it intends to reference them later.

The profile type is given by the following enumeration:

Enumeration Data Type: VpProfileType:
VP_PROFILE_DEVICE /* Device profile */
VP_PROFILE_AC /* AC Profile */
VP_PROFILE_DC /* DC Profile */
VP_PROFILE_RING /* Ringing Profile */
VP_PROFILE_RINGCAD /* Ringing Cadence Profile */
VP_PROFILE_TONE /* Tone Profile */
VP_PROFILE_METER    /* Metering Profile */
VP_PROFILE_CID    /* Caller ID Profile */
VP_PROFILE_TONECAD /* Tone Cadence Profile */ 

The pProfileIndex parameter determines which profile in the table is updated. The argument should be of the form VP_PTABLE_INDEXx, where x is the index into the profile table. This value x must not be larger than number of entries in the profile table for the given profile type. Refer to Table 2-2 for the maximum value for pProfileIndex for each profile type. If pProfileIndex is VP_PTABLE_NULL, this function returns VP_STATUS_INVALID_ARG.

If pProfile is VP_PTABLE_NULL, this function marks the profile table entry as uninitialized. Subsequent VP-API-II function calls attempting to use this profile table entry return the VP_STATUS_ERR_PROFILE error code.

Notes:

1. The application can overwrite an existing profile table entry using this function. However, the new profile will not be applied to any lines until explicitly requested by a subsequent VP-API-II function call such as VpInitDevice(), VpSetLineTone(), etc.
2. All VP-API-II functions that take profile pointers return VP_STATUS_ERR_PROFILE if called with a profile table index pointing to an uninitialized profile table entry. The application must call this function to initialize a profile table entry before attempting to use that profile table entry.

RETURNS

See VP-API-II Function Return Type, on page 10

EVENTS

None

GENERATED

DEVICES

VE792, VCP

TERMINATIONS

All

6.2.10 VpSetBatteries()

SYNTAX vpStatusType

VpSetBatteries(
    VpLineCtxType *pLineCtx, /* Pointer to line context */
    VpBatteryModeType battMode,    /* Indicates to enable or disable use of programmed battery voltages */
    VpBatteryValuesType *pBatt)    /* Pointer to structure specifying battery voltages */

DESCRIPTION
This function enables or disables the use of the programmed battery voltages used by the device for DC feed purposes, to override the measured values. It can improve performance if the application battery voltages are stable to within a lesser tolerance than what the device itself can measure.
The battMode parameter determines whether the programmed values or the device's internal battery sense will be used for DC feed computations. The values of battMode are:
    Enumeration Data Type: VpBatteryModeType:
    VP_BATT_MODE_DIS /* Use device measured batteries */
    VP_BATT_MODE_EN /* Use programmed batteries */
When battMode is VP_BATT_MODE_EN, the structure passed in pBatt must be specified as follows:
    typedef struct VpBatteryValuesType {
    int16 batt1;
    int16 batt2;
    int16 batt3;
};

Where batt1, batt2, and batt3 correspond to the battery configuration found in Table 5-4. Values for batt1, batt2, and batt3 are in two's complement format representing a range of +/-200V (12.21 mV/step).
If battMode is VP_BATT_MODE_EN and pBatt is VP_NULL this function returns VP_STATUS_INVALID_ARG.
When battMode is VP_BATT_MODE_DIS, the structure passed is ignored and may be VP_NULL.
Notes:
1. Even though this function accepts a Line Context pointer (pLineCtx), it affects all lines on the device.

RETURNS
See VP-API-II Function Return Type, on page 10

EVENTS GENERATED
None

DEVICES VCP, VE792, MeLT

TERMINATIONS All 

7 CONTROL FUNCTIONS

7.1 OVERVIEW

This chapter covers VP-API-II functions that primarily control the VTD. The following control functions are described in this chapter:

• VpSetLineState() – Sets a line to the requested state.
• VpSetLineTone() – Generates a cadenced tone on a line.
• VpSetRelayState() - Sets the line relay configuration.
• VpSetRelGain() – Sets the relative transmit or receive gain for a line.
• VpSendSignal() – Generates message waiting pulse on FXS lines, or pulse and DTMF digits on FXO lines.
• VpSendCid() – Starts a Caller ID sequence on a FXS line without waiting for a ring state change.
• VpContinueCid() – Refreshes the Caller ID buffer for a FXS line during message transmission.
• VpStartMeter32Q() - Starts metering on an FXS line.
• VpSetOption() – Sets various device and line specific options.
• VpSetBFilter() – Enables with the coefficients provided or disables the B-Filter.
• VpLineIoAccess() – Controls input/output pins for a specific line.
• VpDeviceIoAccessExt() – Controls device input/output pins. An extended replacement for VpDeviceIoAccess().
• VpLowLevelCmd16() – Allows the application to issue low level commands to the 792 series SLAC. This function is an internal debugging tool that should not be used by the application.
• VpGenTimerCtrl() - Provides control of the SLAC built-in general purpose timers.

7.2 FUNCTION DESCRIPTIONS

7.2.1 VpSetLineState()

SYNTAX vpStatusType

VpSetLineState(

VpLineCtxType *pLineCtx, /* Pointer to line context */

VpLineStateType state) /* Selects the desired line state */

DESCRIPTION

This function sets the line associated with pLineCtx to the requested line state. All possible line states are listed below (note that not all devices or termination types support all states).

Enumeration Data Type: VpLineStateType:
/* The following states are supported for FXS termination only */
VP_LINE_STANDBY /* On-hook, Voice Disabled with normal polarity */
VP_LINE_STANDBY_POLREV /* On-hook, Voice Disabled with reverse polarity */
VP_LINE_TIP_OPEN /* Ground-start idle signaling state */
VP_LINE_RING_OPEN /* Voltage feed on Tip lead only. Useful for testing */
VP_LINE_ACTIVE /* Normal off-hook Active State; Voice Disabled */
VP_LINE_ACTIVE_POLREV /* Normal Active with reverse polarity; Voice Disabled */
VP_LINE_TALK /* Normal off-hook Active State; Voice Enabled */
VP_LINE_TALK_POLREV /* Normal Active with reverse polarity; Voice Enabled */
VP_LINE_OHT /* On-hook Transmission, Voice Enabled with normal polarity */
VP_LINE_OHT_POLREV /* On-hook Transmission, Voice Enabled with reverse polarity */
VP_LINE_DISCONNECT /* Line out of service; voltage sense enabled */
VP_LINE_RINGING /* Ringing (with or without cadence) on the Line */
VP_LINE_PARK /* Oscillatory state between disconnect and feed */
VP_LINE_HOWLER /* Voice disabled, high gain; impedance generation off */
VP_LINE_TESTING /* Line testing state used by VoicePath Test Library */
VP_LINE_DISABLED /* Lowest power; voltage sense disabled */
VP_LINE_NULLFEED /* Voice enabled; Tip and Ring voltages equal */ 

In the VP_LINE_RINGING state, the VP-API-II may perform ringing cadencing and/or Caller ID transmission, according to the profiles specified in the last call to VpInitRing(). Ringing may be applied to and removed from the line synchronized with the zero-crossing of the ringing signal. The operation of the ringing entry and exit can be modified using the vpSetOption() function. If a relay is supported by the termination type, it must be set to VP_RELAY_NORMAL to allow the VTD to control the ringing relay when using external ringing. See VP_OPTION_ID_RING_CNTRL, on page 38 and VP_OPTION_ID_ZERO_CROSS, on page 33 for more details.

Transients that occur as a result of changing line state can be managed by VP OPTION ID DCFEED SLOPE, on page 46.

Notes:

1. VpInitDevice() places all lines in the VP_LINE_DISCONNECT state, which effectively disconnects the lines from the loop. The application must call VpSetLineState() after initialization to enable service to the customer.
2. VP_LINE_PARK state oscillates between VP_LINE_DISCONNECT and VP_LINE_STANDBY. The time in VP_LINE_DISCONNECT and VP_LINE_STANDBY for VP_LINE_PARK are set by VP_DEVICE_OPTION_ID_PARK_MODE.
3. A new line state request by the application is assumed to be a higher priority than any other currently set state or conflicting cadence. Therefore, setting a line state will immediately stop a currently running Caller ID cadence, Ringing Cadence, Metering, or other line state control from any VP-API-II function that affects the line state. A state change that only performs a polarity reversal between otherwise identical states will not stop the generation of metering pulses or the generation of call processing tones.
4. Setting a line to a state does not affect Tone Cadencing (except possibly the analog performance by changing the line state). If metering is being generated, the current meter pulse will continue until complete, then will terminate without generating the remaining meter pulses (if any). If the pulse is defined as "always on", it will terminate immediately.
5. In the line state descriptions above, the phrase "voice-enabled" indicates that the PCM port is enabled, thus allowing PCM transmission (unless overridden by the VP_OPTION_ID_PCM_TXRX_CNTRL option). In addition to all "voice-enabled" states, the internal signal generators are also enabled in the VP_LINE_ACTIVE, VP_LINE_ACTIVE_POLREV, and VP_LINE_HOWLER states. As a result, a tone can be produced by the SLAC using the VpSetLineTone() function in these states, even though the PCM port is disabled.
6. The VP_LINE_RINGING_POLREV line state is only needed for VCP-790 and VCP2-790 applications. In all other applications, this state is identical to VP_LINE_RINGING. In VCP-790 applications, the VP_LINE_RINGING_POLREV line state does not effect the polarity of the generated signal; the generated signal is the same for VP_LINE_RINGING and VP_LINE_RINGING_POLREV. The AC and DC levels are entirely defined by the Ringing Profile. However, depending on the polarity specified in the Ringing Profile, the corresponding line state must be selected to allow long-loop ring trip detection to work correctly.

RETURNS

See VP-API-II Function Return Type, on page 10

EVENTS

GENERATED

None.

DEVICES All

TERMINATIONS All

7.2.2 VpSetLineTone()

SYNTAX vpStatusType
VpSetLineTone( VpLineCtxType pLineCtx, / Pointer to line context */

VpProfilePtrType
pToneProfile,    /* Pointer to Tone Profile */

VpProfilePtrType
pCadProfile,    /* Pointer to Tone Cadence Profile */

VpDtmfToneGenType
*pDtmfControl)

DESCRIPTION This function starts a call progress tone with an optional cadence on the line associated with pLineCtx. The generated tone is defined by the Tone Profile at pToneProfile. If pToneProfile is VP_PTABLE_NULL, then any currently active tone is stopped. The cadence (on/off sequence) applied to the tone is defined by the Cadence Profile at pCadProfile. If pCadProfile is VP_PTABLE_NULL, then the specified tone is played continuously until turned-off with a subsequent call to VpSetLineTone(). The argument pDtmfControl must be VP_NULL.controls DTMF tone generation. If this argument is not VP_NULL, a DTMF tone will be generated, and pToneProfile must be VP_PTABLE_NULL. The DTMF control structure is defined below.

Enumeration Data Type: VpDigitType: 1 to 9 / Digits 1 to 9; No constants defined for this / VP_DIG_ZERO / Digit 0 / VP_DIG_ASTER / "" key on the telephone keypad / VP_DIG_POUND / "" key on the telephone keypad / VP_DIG_A / "A" key on the telephone keypad / VP_DIG_B / "B" key on the telephone keypad / VP_DIG_C / "C" key on the telephone keypad / VP_DIG_D / "D" key on the telephone keypad / VP_DIG_NONE / Stop digit generation /

Enumeration Data Type: VpDirectionType: VP_DIRECTION_DS / Tone generation in downstream direction / VP_DIRECTION_US / Tone generation in upstream direction /

typedef struct { VpDigitType toneId, / The requested DTMF tone / VpDirectionType dir, / DTMF tone generation direction / } VpDtmfToneGenType;

Notes: 1. Call progress tone and DTMF tone generation cannot be performed simultaneously. 2. DTMF tone generation is supported only in the downstream direction. 3. The UK or Australian Howler tone are generated by using appropriate tone and cadence profiles produced by Profile Wizard just like with any other tone, after selecting the VP_LINE_HOWLER state with VpSetLineState().

RETURNS See VP-API-II Function Return Type, on page 10

EVENTS GENERATED VP_LINE EVID TONE CAD, on page 73

DEVICES VE792, VCP

TERMINATIONS All

7.2.3 VpSetRelayState()

SYNTAX vpStatusType

VpSetRelayState(

VpLineCtxType *pLineCtx, /* Pointer to line context */

VpRelayControlType rState) /* Relay state */

DESCRIPTION

This function configures the VTD-controlled relays or LCAS. Depending on the line termination type, the VTD may have control over some combinations of LCAS or electro-mechanical relay states and test load. The line circuit configuration determines the allowable parameters for rState. This function returns an error if the rState argument tries to control a relay that is not included in the reference design circuit (as specified in the call to VpMakeLineObject(). on page 22 through the line termination type). The relay states are listed below.

Enumeration Data Type: VpRelayControlType:
VP_RELAY_NORMAL
VP_RELAY_RESET
VP_RELAY_TESTOUT
VP_RELAY_TALK
VP_RELAY_RINGING
VP_RELAY_TEST
VP_RELAY_BRIDGED_TEST
VP_RELAY_SPLIT_TEST
VP_RELAY_DISCONNECT
VP_RELAY_RINGING_NOLOAD
VP_RELAY_RINGING_TEST
VP_RELAY_LAMP_ON 

The VP_RELAY_NORMAL state allows for normal VTD control of the LCAS or relay(s) according to the current line state selected by the VpSetLineState() function and any fault condition detected. Selection of any other relay state overrides the automatic VTD relay control. The LCAS, relay, and test load are forced into the desired state without consideration for the current SLIC/SLAC state.

The appendix Relay Configurations, on page 167 includes simplified connection diagrams for applicable relay states for various line termination types.

RETURNS

See VP-API-II Function Return Type, on page 10

EVENTS GENERATED

None

DEVICES All

TERMINATIONS All

7.2.4 VpSetRelGain()

SYNTAX vpStatusType

VpSetRelGain(

VpLineCtxType *pLineCtx, /* Pointer to line context */

uint16 txLevel, /* Relative adjustment to Tx level */

uint16 rxLevel, /* Relative adjustment to Rx level */

uint16 handle) /* Handle returned with event */

DESCRIPTION

This function adjusts the transmit and receive gain for the specified line. The gain adjustment is made relative to the gain levels set in the AC Profile applied to the line. Setting the txLevel or rxLevel to 1.0 resets the respective path to the default gain from the AC Profile.

The transmit and receive gains are specified as 2.14 fixed-point unsigned numbers with a range of 0 to 4.0 (actually 3.9999) of absolute gain adjustment. The amount of adjustment possible depends on the zero transmission level point (0 TLP) set in the AC Profile. The application can be coded to know that the 0 TLP allows for a guaranteed adjustment range, or it can get the default gain level by setting the txLevel and rxLevel inputs to 1.0 and compute the available adjustment range using the data returned with the VP_LINE_EVID_GAIN_CMP event.

The VP_LINE_EVID_GAIN_CMP event occurs once the VTD has applied the new gain settings. The results of this function are described in Section 5.5.8 with the definition of this event.

RETURNS

See VP-API-II Function Return Type, on page 10

EVENTS

VP LINE EVID GAIN CMP. on page 67

GENERATED

DEVICES VE792, VCP

TERMINATIONS All

7.2.5 VpSendSignal()

SYNTAX VpStatusType

VpSendSignal(
    VpLineCtxType *pLineCtx, /* Pointer to line context */
    VpSendSignalType signalType, /* Specifies the type of signal */
    void *pSignalData) /* Specifies signal parameters */

DESCRIPTION
This function generates a signal on the specified line. The following types of signals are defined:
Enumeration Data Type: VpSendSignalType:
    VP_SENDSIG_MSG_WAIT_PULSE /* Send message waiting signal */
    VP_SENDSIG_FWD_DISCONNECT /* Generate a Forward Disconnect */
    VP_SENDSIG_POLREV_PULSE /* Generate a Polarity Reversal */

For each of the above signal types, the pSignalData argument points to an initialized instance of a structure or a variable that defines the signal.
When sending a message waiting signal (VP_SENDSIG_MSG_WAIT_PULSE), pSignalData must point to a VpSendMsgWaitType instance. The VpSendMsgWaitType structure is defined as follows:
typedef struct {
    int8 voltage, /* Voltage (Volts) applied to the line. A
    * negative value means Tip is more negative than
    * Ring, a positive value means Ring is more
    * negative than Tip. */
    uint16 onTime, /* Duration of pulse on-time in mS. If the
    * on-time is 0 it stops an ongoing message
    * waiting signal generation. */
    uint16 offTime, /* Duration of pulse off-time in mS. If the
    * off-time is set to 0, the voltage is applied
    * to the line continuously. */
    uint8 cycles, /* Number of pulses to send on the line. If set
    * to 0, will repeat forever. */
} VpSendMsgWaitType;
When sending a Forward Disconnect, pSignalData must point to a uint16 instance specifying the time in the disconnect state in milli-seconds. No hook events will occur when entering disconnect, while in disconnect, and for 100ms after recovery from the disconnect state.
When sending a Polarity Reversal, pSignalData must point to a uint16 instance specifying the time in the polarity reversal state in milli-seconds. No hook events will occur for 100ms after changing the polarity state. The specific state used for Polarity Reversal is the reverse polarity of the current state (i.e., if currently in VP_LINE_TALK_POLREV, then Polarity Reversal will be VP_LINE_TALK).
The VP_LINE_EVID_SIGNAL_CMP event occurs when signal generation is done.
RETURNS
See VP-API-II Function Return Type, on page 10
EVENTS
GENERATED
VP_LINE EVID_SIGNAL_CMP, on page 73
DEVICES VE792, VCP
TERMINATIONS
All 

7.2.6 VpSendCid()

SYNTAX vpStatusType

VpSendCid(

VpLineCtxType *pLineCtx, /* Pointer to line context */

uint8 length, /* Length of the CID data to send */

VpProfilePtrType pCidProfile,

/* Pointer to Caller ID Profile */

uint8p pCidData) /* Pointer to Caller ID data */

DESCRIPTION

VpSendCid() transmits Caller ID data on-demand. This function differs from VpInitCid() in that VpInitCid() sends Caller ID data automatically during the ringing cadence. This function enables off-hook Caller ID, also known as Type-II or Call Waiting Caller ID. VpSendCid() is a more flexible method of sending Caller ID than VpInitCid().

The length argument should specify the total length in bytes of the entire message to be transmitted if the message length is less than or equal to 32 bytes, otherwise it should be set to 32. Since Caller ID messages can be longer than 32 bytes, the application may need to make several VP-API-II function calls to transmit a complete Caller ID message. To facilitate this, the VP-API-II generates the VP_LINE_EVID_CID_DATA event (with eventdata equal to VP_CID_DATA_NEED_MORE_DATA) when 16 bytes of Caller ID data remain in the transmit buffer. It takes approximately 133 ms to send 16 bytes of CID data. Upon receiving this event, the application must call vpContinueCID() to buffer any remaining Caller ID data. If this function is called with length less than or equal to 16 bytes, then the VP-API-II assumes that the Caller ID message is not longer than 16 bytes and therefore does not generate the VP_CID_DATA_NEED_MORE_DATA event.

The pCidProfile argument selects the desired Caller ID Profile. The timing information present in the Caller ID Profile, such as the relationship between the start of Caller ID transmission and the ringing cadence, is not applicable to this function and is ignored.

The pCidData argument should point to a buffer containing the Caller ID message. Refer to VplnitCid(). on page 85 for move information on handling the Caller ID data.

Notes:

1. If a Caller ID sequence is terminated due to the CPE not sending the ACK signal, the VTD does not generate any event to indicate the termination of the CID sequence.

RETURNS

See VP-API-II Function Return Type, on page 10

EVENTS

GENERATED

VP LINE EVID CID DATA. on page 72

DEVICES VE792, VCP

TERMINATIONS All

7.2.7 VpContinueCid()

SYNTAX VpStatusType

VpContinueCid(

VpLineCtxType *pLineCtx, /* Pointer to line context */

uint8 length /* Length of Caller ID data */

uint8p pCidData) /* Pointer to the Caller ID data */

DESCRIPTION

This function writes Caller ID data to the VTD Caller ID data buffer. This function should be called each time theVP_LINE_EVID_CID_DATA:VP_CID_DATA_NEED_MORE_DATA event occurs and there is additional Caller ID data to transmit on the relevant line. If VpContinueCID() is not called in response to this event, then the VTD transmits the remaining message data followed by the checksum (if indicated in the caller id profile) with the previous buffer contents. This function is necessary for both Type-I and Type-II Caller ID implementations.

The length argument should specify the length in bytes of the buffer pointed to by pCidData but not to exceed 16. When the device is able to accept at least 16 more bytes of Caller ID data, the VP-API-II generates the VP_LINE_EVID_CID_DATA event with eventdata equal to VP_CID_DATA_NEED_MORE_DATA. Upon receiving this event, the application must call VpContinueCID() to buffer any remaining Caller ID data. If this function is called with length less than or equal to 16 bytes, then the VP-API-II assumes that the Caller ID message is not longer than 16 bytes and therefore does not generate the VP_LINE_EVID_CID_DATA: VP_CID_DATA NEED MORE_DATA event.

The pCidData argument should point to a buffer containing the next segment of Caller ID data, up to 16 bytes in length. Data blocks longer than 16 bytes are not supported.

The VP_LINE_EVID_CID_DATA:VP_CID_DATA_TX_DONE event occurs once all of the Caller ID data is transmitted or when CID is aborted.

RETURNS

See VP-API-II Function Return Type, on page 10

EVENTS

GENERATED

VP LINE EVID CID DATA, on page 72

DEVICES VE792, VCP

TERMINATIONS All

7.2.8 VpStartMeter32Q()

SYNTAX vpStatusType

VpStartMeter32Q(
    VpLineCtxType *pLineCtx, /* Pointer to line context */
    uint32 minDelay,    /* Delay before pulse start in 1ms increments */
    uint32 onTime, /* Pulse on time in 1ms increments */
    uint32 offTime, /* Pulse off time in 1ms increments */
    uint16 numMeters /* Number of meter cycles to perform */
    uint16 eventRate)    /* Number of meter cycles to perform between each Meter Cadence Event */ 

DESCRIPTION

This function starts metering pulses on the line associated with the line context argument pLineCtx. The metering behavior is defined by minDelay, onTime, offTime, and numMeters.

Table 7-1 VpStartMeter32Q() Behavior

onTime numMeters Result
0 0 Stops a currently-running meter sequence
0	>0	Generates a meter pulse of duration of 2^32 ms in length
t	0	Generates metering pulses indefinitely (until otherwise stopped by the application) with on-time of t ms
t	n	Generates n number of metering pulses with on-time of t ms

The value minDelay is used to guarantee a minimum time between the last metering pulse on-time (specified by a previous VpStartMeter32Q() call) to the start of the next metering pulse on-time (specified by the current VpStartMeter32Q() call).

By using a combination of values passed to this function and response to VP_LINE_EVID_MTR_ROLLOVER, any number of metering pulses can be generated all with precise on and off times.

The parameter eventRate allows the application to control the interval between VP_LINE_EVID_MTR_CAD events. It is specifically the number of pulses that have to occur before a VP_LINE_EVID_MTR_CAD event is generated (i.e., higher number is a "quieter" system since more pulses have to be sent in between events). This feature is particularly useful in high line count applications where it would be desirable to minimize the number of interrupts over a given period of time.

Notes:

1. For backward compatibility, specifying eventRate = 0 means the same as eventRate = 1. In this case, a VP_LINE_EVID_MTR_CAD event will be generated at the completion of each meter pulse. The normal VP_OPTION_ID_EVENT_MASK mechanism can be used to disable all VP_LINE_EVID_MTR_CAD events, if desired.
2. When aborting an ongoing meter cadence (by passing on Time = numMeters = 0), the eventRate parameter should not be changed from the previous value.

RETURNS

See VP-API-II Function Return Type, on page 10

EVENTS

GENERATED

VP LINE EVID MTR CMP, on page 71

VP LINE EVID MTR ABORT, on page 71

VP LINE EVID MTR CAD, on page 71

VP LINE EVID MTR ROLLOVER, on page 72

DEVICES VCP2-792, VE792

TERMINATIONS All

7.2.9 VpSetOption()

SYNTAX vpStatusType

VpSetOption(

VpLineCtxType *pLineCtx, /* Pointer to line context */

VpDevCtxType *pDevCtx, /* Pointer to the Device Object */

VpOptionIdType option, /* Selects the option to modify */

void *pValue) /* Pointer to the option's new value */

DESCRIPTION

This function sets an option to the specified value for one or more lines. The option argument determines which option is modified. Options may be line-specific or device-specific. Refer to Chapter 4, on page 29 for a complete list and definition of all VP-API-II options.

This function acts on one line, or all lines of the device, depending on the values of the device context, line context, and option arguments. The table below summarizes this behavior. The "Option" column indicates whether the target option is device-specific or line-specific. The "Device Ctx" and "Line Ctx" columns indicate whether a valid pointer or VP_NULL is passed for the pDevCtx and pLineCtx parameters, respectively.

Table 7-2 VpSetOption() Behavior

Option Device Ctx Line Ctx Result
device-specific	VP_NULL	VP_NULL	returns VP_STATUS_INVALID_ARG
device-specific	VP_NULL	valid	returns VP_STATUS_INVALID_ARG
device-specific	valid	VP_NULL	sets option for the specified device
device-specific	valid	valid	returns VP_STATUS_INVALID_ARG
line-specific	VP_NULL	VP_NULL	returns VP_STATUS_INVALID_ARG
line-specific	VP_NULL	valid	sets option for the specified line
line-specific	valid	VP_NULL	sets option for all lines of the specified device
line-specific	valid	valid	returns VP_STATUS_INVALID_ARG

The arguments required for each option are different. Therefore, a void pointer (pValue) is provided as the option input parameter to the function. This argument must point to an initialized instance of the input structure related to the target option. For example, if the device critical fault options are being set (VP_DEVICE_OPTION_ID_CRITICAL_FLT), then pValue must point to an initialized instance of VpOptionCriticalFltType. Chapter 4, on page 29 describes the input parameter type for each option.

All options are set to their default values after the device is initialized as a result of calling the VpInitDevice() function. Therefore, options should only be changed after device initialization is complete, as indicated by the VP_DEV_EVID_DEV_INIT_CMP event. Line-specific options are also reset as a result of calling the VpInitLine() function. The application should set these line-specific options to their desired values after line initialization is complete, as indicated by the VP_LINE_EVID_LINE_INIT_CMP event.

RETURNS

See VP-API-II Function Return Type, on page 10

EVENTS

GENERATED

None.

DEVICES All

TERMINATIONS All

7.2.10 VpSetBFilter()

SYNTAX vpStatusType

VpSetLineState(
    VpLineCtxType *pLineCtx, /* Pointer to line context */
    VpBFilterModeType bFiltMode,    /* Selects the desired B-Filter Mode (enable or disable) */
    VpProfilePtrType pAcProfile)    /* Pointer to AC profile containing desired B-Filter values to program. Used if B-Filter being enabled */ 

DESCRIPTION This function enables or disables the B-Filter on the line associated with pLineCtx. The valid settings for bFiltMode are listed below.
Enumeration Data Type: VpBFilterModeType:
    /* The following states are supported for FXS termination only */
    VP_BFILT_DIS /* Disable the B-Filter */
    VP_BFILT_EN /* Enable the B-Filter */

If VP_BFILT_EN is passed, then values provided in pAcProfile are loaded into the device. If VP_BFILT_DIS is passed, the B-Filter is disabled.
If VP_BFILT_EN is passed and pAcProfile is VP_PTABLE_NULL, the previous B-filter setting is retained. 

RETURNS See VP-API-II Function Return Type, on page 10 

EVENTS GENERATED None. 

DEVICES VCP-790, VCP2-792, VE792 

TERMINATIONS All 

7.2.11 VpLineloAccess()

SYNTAX vpStatusType

VpLineIoAccess(
    VpLineCtxType *pLineCtx, /* Pointer to line context */
    VpLineIoAccessType *pLineIoAccess,    /* Struct containing access type and values to be written */
    uint16 handle)    /* Handle value returned with event */

DESCRIPTION
This function accesses some or all of the general-purpose input/output (GPIO) pins associated with a particular line. Refer to VP_OPTION_ID_LINE_IO_CFG on page 41 for information on I/O pin configuration and restrictions. This function takes a pointer to the following structure type:
    typedef struct {
    VpIoDirectionType direction;
    VpLineIoBitsType ioBits;
    } VpLineIoAccessType;
The direction field determines whether a read or write operation is performed on the I/O pins. It can take on the following values:
    typedef enum {
    VP_IO_WRITE,
    VP_IO_READ,
    } VpIoDirectionType;
The ioBits field is a VpLineIoBitsType struct:
    typedef struct {
    uint8 mask;
    uint8 data;
} VpLineIoBitsType;
The mask field contains a bit for each GPIO pin associated with the line. For each bit in this field, if the bit is set, then the corresponding GPIO pin is accessed; if the bit is 0, then the corresponding GPIO pin is left alone. Some GPIO pins are reserved to control relays or device states via the command VpSetRelayState(). on page 93, those pins must have a 0 in their corresponding bit in the mask field. A VP_STATUS_DEDICATED_PINS error code will be returned if the mask field contains a 1 for a reserved GPIO pin.
The data field also contains a bit for each GPIO pin associated with the line. For write operations (VP_IO_WRITE), the GPIO pins are set to the values specified in this field only if the corresponding bit in the mask field is set. For read operations (VP_IO_READ), the values of the GPIO pins are returned with the VP_LINE_EVID_LINE_IO_RD_CMP event only if the corresponding bit in the mask field is set (otherwise 0 is returned).
For write operations, the VP_LINE_EVID_LINE_IO_WR_CMP event occurs when the GPIO write command is done. For read operations, the VP_LINE_EVID_LINE_IO_RD_CMP event occurs when the GPIO read command is done. Upon receiving the VP_LINE_EVID_LINE_IO_RD_CMP event, the VpGetResults() function should be called to place the results into a VpLineIoAccessType buffer.

RETURNS
See VP-API-II Function Return Type. on page 10

EVENTS
VP_LINE_EVID_LINE_IO_RD_CMP. on page 68
GENERATED
VP_LINE_EVID_LINE_IO_WR_CMP. on page 69 

DEVICES VCP2, VE792, MeLT-VCP

TERMINATIONS All

7.2.12 VpDeviceAccessExt()

SYNTAX vpStatusType

VpDeviceIoAccessExt(
    VpDevCtxType *pDevCtx, /* Pointer to device context */
    VpDeviceIoAccessExtType *pDeviceIoAccess) /* Struct containing access type and values to be written */

DESCRIPTION This function accesses some or all of the general-purpose input/output (GPIO) pins associated with a device in a single operation. Refer to VP_DEVICE_OPTION_ID_DEV_IO_CFG, on page 40 and VP_OPTION_ID_LINE_IO_CFG on page 41 for information on I/O pin configuration and restrictions. This function takes a pointer to the following structure type:
    typedef struct {
    VpIoDirectionType direction;
    VpLineIoBitsType lineIoBits[VP_MAX_LINES_PER_DEVICE];
    } VpDeviceIoAccessExtType;
The direction field determines whether a read or write operation is performed on the I/O pins. It can take on the following values:
    typedef enum {
    VP_IO_WRITE,
    VP_IO_READ,
    } VpIoDirectionType;
The lineIoBits array contains a VpLineIoBitsType element for each line controlled by the device. See VpLineloAccess(), on page 102 for a description of this struct containing line-specific GPIO access information. The first VpLineIoBitsType element pertains to the lowest line number and the subsequent ones follow in order of increasing line numbers. The number of array elements is VP_MAX_LINES_PER_DEVICE, a compile-time option specified in vp_api_cfg_int.h. For VE792 devices, the value is 8.
This function generates the VP_DEV_EVID_IO_ACCESS_CMP event indicating that the requested I/O access is done. The results of an I/O read operation are returned when this event occurs. Refer to Section 5.5.11 for details. Upon receiving the VP_DEV_EVID_IO_ACCESS_CMP event, the VpGetResults() function should be called to place the results into the VpDeviceIoAccessExtType buffer.

RETURNS See VP-API-II Function Return Type, on page 10
EVENTS GENERATED VP_DEV_EVID_IO_ACCESS_CMP, on page 68

DEVICES VCP2, VE792, MeLT-VCP

TERMINATION S All 

7.2.13 VpLowLevelCmd16()

SYNTAX vpStatusType

VpLowLevelCmd16(
    VpLineCtxType *pLineCtx, /* Pointer to line context */
    VpLowLevelCmdType cmdType, /* Details below */
    uint16 *writeWords, /* Buffer of words to write (if any) */
    uint8 numWriteWords, /* Number of words to write */
    uint8 numReadWords, /* Number of words to read */
    uint16 handle) /* Handle value returned with event */ 

DESCRIPTION

This function is not recommended for use by the customer. It circumvents the Host Test Library (if used) and the VP-API-II, providing direct access to the 792-series SLAC. Improper use of this function could break the synchronization within the system, resulting in unpredictable behavior. This function is implemented to enable debugging and should only be used when working closely with Microsemi customer support.

Refer to the 792 series SLAC Chip Set User's Guide for a description of the low-level commands that may be used with this function.

This function can issue both read and write commands defined by VpLowLevelCmdType enumeration.

typedef enum {
    VP_LOWLEV_PAGE_WR,    /* Paged Write */
    VP_LOWLEV_PAGE_RD,    /* Paged Read */
    VP_LOWLEV_MBOX_WR,    /* Mailbox Write */
    VP_LOWLEV_MBOX_RD    /* Mailbox Read */
} VpLowLevelCmdType; 

The pLineCtx argument identifies the device/channel to which the command is issued.

The writeWords argument points to a command/data string whose format and content must comply with the 792 series SLAC device.

The numWriteWords argument specifies the total number of words to write to the SLAC interface.

The numReadWords arguments specifies the number of words to read from the SLAC interface. This argument applies only to read operations (otherwise is ignored).

Limits for the numWriteWords and numReadWords arguments are shown in the following table:

Table 7-3 VpLowLevelCmd16() argument ranges

Device Command Type numWrite Words numReadWords
VE792 MELT-792	VP_LOWLEV_PAGE_WR	1-128	0
	VP_LOWLEV_PAGE_RD	1-2 1-128
	VP_LOWLEV_MBOX_WR	2-64	0
	VP_LOWLEV_MBOX_RD	2-64 1-64

The handle argument is returned with the completion event (VP_LINE_EVID_LLCMD_RX_CMP event only).

For write operations, the VP_LINE_EVID_LLCMD_TX_CMP event occurs. For read operations, the VP_LINE_EVID_LLCMD_RX_CMP event occurs.

Upon receiving the VP_LINE_EVID_LLCMD_RX_CMP event, the VpGetResults() function should be called to place the results into a buffer of numReadWords size.

RETURNS See VP-API-II Function Return Type, on page 10

EVENTS VP LINE EVID LLCMD TX CMP, on page 63

GENERATED VP LINE EVID LLCMD RX CMP, on page 63

DEVICES VCP2-792, VE792, MeLT

TERMINATIONS All

7.2.14 VpGenTimerCtrl()

SYNTAX vpStatusType

VpGenTimerCtrl(
    VpLineCtxType *pLineCtx, /* Pointer to line context */
    VpGenTimerCtrlType timerCtrl, /* Details below */
    uint32 duration, /* Time specified in ms (if starting) */
    uint16 handle) /* Handle value returned with event */

DESCRIPTION
This function provides control of the SLAC's built-in general-purpose timer. There is one timer per SLAC. The timer options are specified by the VpGenTimerCtrlType enumeration.
typedef enum {
    VP_GEN_TIMER_START
    VP_GEN_TIMER_CANCEL
} VpGenTimerCtrlType;

If canceling a timer you must pass the same pLineCtx and handle parameters as when you started the timer.
Notes:
1. The Test Library uses the SLAC's built-in timer, so this function should not be called on any SLAC on which there is an ongoing test.

RETURNS
See VP-API-II Function Return Type, on page 10

EVENTS
GENERATED
VP_LINE_EVID_GEN_TIMER, on page 74 

DEVICES VCP2-792, VE792, MeLT

TERMINATIONS All

8 STATUS AND QUERY FUNCTIONS

Microsemi.

8.1 OVERVIEW

This chapter describes VP-API-II functions that get information and events from the VTD, including the following:

• VpGetEvent() – Returns events corresponding to a device.
• VpGetLineStatus() – Returns the state of a particular status flag for one line.
• VpGetLoopCond() – Reads loop conditions for a line and returns parameters such as voltage, current, and resistance.
• VpGetOption() – Returns the current setting of an option.
• VpGetLineState() – Reads the current line state.
• VpFlushEvents() – Flushes all outstanding events.
• VpGetResults() – Reads the data associated with an event.
• VpClearResults() – Discards the data associated with an event.
• VpGetDeviceStatusExt() – Returns the state of a particular status flag for all lines of a device.

8.2 FUNCTION DESCRIPTIONS

8.2.1 VpGetEvent()

SYNTAX bool

VpGetEvent(

VpDevCtxType *pDevCtx, /* Pointer to device context */

VpEventType *pEvent) /* Pointer to target event data buffer */

DESCRIPTION

The VpGetEvent() function reports a single VTD event. This function should be called whenever the VTD interrupt occurs. If it returns an event, it must be called again until there are no more events in the event queue.

The pDevCtx argument must point to the context of the VTD that is reporting an event. The pEvent argument must point to an application buffer for the event data returned by this function. The application buffer should be of VpEventType type, which is defined as follows:

typedef struct {
    VpStatusType status; /* Function return status */
    uint8 channelId; /* Channel which caused the event */
    VpLineCtxType *pLineCtx; /* Pointer to the line context corresponding to
    * the line that caused the event */
    VpLineIdType lineId;    /* Application provided line Id to ease mapping
    * of lines to specific line contexts. */

    VpDeviceIdType deviceId; /* Id of the device that caused the event */
    VpDevCtxType *pDevCtx;    /* Pointer to the device context corresponding to
    * the device that caused the event */

    VpEventCategoryType
    eventCategory; /* Event category */
    uint16 eventId;    /* Unique event ID (within event category) */
    uint16 parmHandle;    /* Event's parameter or application handle */
    uint16 eventdata;    /* Data associated with the event */
    bool hasResults;    /* Indicates whether event has extra results */
} VpEventType; 

The status variable indicates whether an error occurred while executing this function. This function's boolean return value indicates whether an event was retrieved from the VTD. The application should interpret these two variables as follows:

• status equal to VP_STATUS_SUCCESS and VpGetEvent() returned TRUE An event was retrieved from the VTD, event data valid.
• status equal to VP_STATUS_SUCCESS and VpGetEvent() returned FALSE No event was retrieved from the VTD, ignore event data.
• status not equal to VP_STATUS_SUCCESS VpGetEvent() encountered an error. Ignore event data and function return value. See VP-API-II Function Return Type, on page 10 for a complete list of error codes.

Events are classified into event categories so that the application can easily process them. The eventCategory member of the event structure indicates which category the event belongs to; eventCategory can be any of the following values:

Enumeration Data Type: VpEventCategoryType:
VP_EVCAT_FAULT    /* Fault event category */
VP_EVCAT_SIGNALING    /* Signaling event category */
VP_EVCAT_RESPONSE    /* Response event category */
VP_EVCAT_TEST    /* Test event category */
VP_EVCAT_PROCESS    /* Call Process event category */ 

The individual event ID is passed through the eventId member of the event structure. Refer to Chapter 5, on page 51 for a complete list of the individual event ID names. Note that the event ID constants are only unique within the applicable event category.

Some event are device-specific, and some events are line-specific. The VpGetEvent() function sets the pLineCtx, lineId, and channelId members according to the event specificity:

Table 8-1 VpEventType Fields Indicating Specificity

Event Type Field Value
Line-specific	pLineCtx	Valid pointer to the Line Context for the line associated with the event
	lineId	The line ID (previously assigned with VpMapLineld()) for the line associated with the event
	channelId	The VTD channel ID for the line associated with the event
Device-specific	pLineCtx	VP_NULL
	lineId (not defined)
	channelId	(not defined)

The parmHandle and eventdata variables contain additional event-specific information. The boolean hasResults variable indicates whether additional data related to the event is present in the mailbox. The application must either retrieve the additional data using VpGetResults() or dequeue the data by calling VpClearResults() before calling VpGetEvent() again.

Chapter 5, on page 51 describes the parmHandle, eventdata, and extended results for each VP-API-II event.

Notes:

This function returns only non-masked events. Events masks are set by calling VpSetOption() with the VP_OPTION_ID_EVENT_MASK option. The default event masks are set when the VpInitDevice() function is called.

RETURNS

TRUE if an event is pending FALSE otherwise. See function description for details.

EVENTS

GENERATED

None—this function is called to retrieve an event.

DEVICES All

TERMINATIONS All

8.2.2 VpGetLineStatus()

SYNTAX vpStatusType

VpGetLineStatus(

VpLineCtxType *pLineCtx, /* Pointer to line context */

VpInputType input /* Test the status of this input type */

bool *pStatus) /* Pointer to status results */

DESCRIPTION

This function obtains the status of the specified input for the line associated with pLineCtx. The status result is written to the location pointed to by the argument pStatus. The following line inputs can be checked with this function:

Enumeration Data Type: VpInputType:
/* FXS Status types */
VP_INPUT_HOOK /* Hook Status (ignoring pulse & flash) */
VP_INPUT_RAW_HOOK /* Hook Status (include pulse & flash) */
VP_INPUT_GKEY /* Ground-Key/Fault Status */
VP_INPUT_THERM_FLT /* Thermal Fault Status */
VP_INPUT_CLK_FLT /* Clock Fault Status */
VP_INPUT_AC_FLT /* AC Fault Status */
VP_INPUT_DC_FLT /* DC Fault Status */
VP_INPUT_BAT1_FLT /* Battery 1 Fault Status */
VP_INPUT_BAT2_FLT /* Battery 2 Fault Status */
VP_INPUT_BAT3_FLT /* Battery 3 Fault Status */ 

The boolean status result, pointed to by pStatus, is interpreted differently depending on the type of input queried:

• Fault flags are either active (TRUE) or inactive (FALSE).
• Hook status is either off-hook (TRUE) or on-hook (FALSE). When automatic pulse-digit decoding is disabled, the values for VP_INPUT_HOOK and VP_INPUT_RAW_HOOK are identical. When pulse-digit decoding is enabled, VP_INPUT_RAW_HOOK reflects the current state of the line's hook detector, while VP_INPUT_HOOK represents the logical hook state after filtering pulse-digit and hook-switch flash events.
  • Ground key status is either active (TRUE) or inactive (FALSE).

Notes:

1. This function returns the status of one input for a single line. VpGetDeviceStatusExt() returns an array of status flags for all lines controlled by a device.
2. An active ground-key may be considered a fault by the application when the line is not used in a ground-start system. Ground-key and DC fault are polarity sensitive and although they both monitor longitudinal currents, either one may appear as an indication of a line fault depending on the polarity of the fault current.
3. See Table 5-4 to convert generic battery names to device-specific battery names.

RETURNS

See VP-API-II Function Return Type, on page 10

EVENTS

None

GENERATED

DEVICES

All

TERMINATIONS

All

8.2.3 VpGetLoopCond()

SYNTAX vpStatusType

VpGetLoopCond(

VpLineCtxType *pLineCtx, /* Pointer to line context */

uint16 handle) /* Handle value returned with event */

DESCRIPTION

This function starts a process that eventually returns the current loop and battery conditions for the specified line. Several measurements are taken from the device when this function is called. However, these measurements may not be taken simultaneously. The VP_LINE_EVID_RD_LOOP event occurs when the results are available for the application to read. The application can execute this function while the target line is in any state. However, some measurement results may not be valid in certain line states. See VP_LINE_EVID_RD_LOOP, on page 64 for details.

4.

RETURNS

See VP-API-II Function Return Type, on page 10

EVENTS

GENERATED

VP LINE EVID RD LOOP, on page 64

DEVICES All

TERMINATIONS All

8.2.4 VpGetOption()

SYNTAX vpStatusType

VpGetOption(

VpLineCtxType *pLineCtx, /* Pointer to line context */

VpDevCtxType *pDevCtx, /* Pointer to the device context */

VpOptionIdType option, /* Selects the option to get */

uint16 handle) /* Handle value returned with event */

DESCRIPTION

This function retrieves the current setting of an option applied to the specified device or line. The option argument determines which option is read. For a list and description of all VP-API-II options see Chapter 4.

VpGetOption() actually starts a process in the VP-API-II/VTD that retrieves the requested data from a device. This function does not wait for the data to become available. Instead, this function returns immediately, and an event occurs at some later time indicating that the requested data is available.

The exact option setting that is retrieved by this function depends on the values of the device context, line context, and option arguments. The table below summarizes this behavior. The "Option" column indicates whether the target option is device-specific or line-specific. The "Device Ctx" and "Line Ctx" columns indicate whether a valid pointer or VP_NULL is passed for the pDevCtx and pLineCtx parameters, respectively.

Table 8-2 VpGetOption() Behavior

Option Device Ctx Line Ctx Result
device-specific	VP_NULL	VP_NULL	returns VP_STATUS_INVALID_ARG
device-specific	VP_NULL	valid	gets option for device that controls the specified line
device-specific	valid	VP_NULL	gets option for the specified device
device-specific	valid	valid	returns VP_STATUS_INVALID_ARG
line-specific	VP_NULL	VP_NULL	returns VP_STATUS_INVALID_ARG
line-specific	VP_NULL	valid	gets option for the specified line
line-specific	valid	VP_NULL	returns VP_STATUS_INVALID_ARG
line-specific	valid	valid	returns VP_STATUS_INVALID_ARG

The VP_LINE_EVID_RD_OPTION event is generated as a result of this function call, indicating that the requested option data is available. The handle argument to VpGetOption() specifies the event handle that is attached to this event. Upon receiving this event, the application must call VpGetResults() with a pointer to the appropriate data structure to retrieve the option settings. The Refer to VP_LINE_EVID_RD_OPTION, on page 64 for more information on retrieving the option data associated with this event.

RETURNS

See VP-API-II Function Return Type, on page 10

EVENTS

GENERATED

VP_LINE_EVID_RD_OPTION, on page 64

DEVICES All

TERMINATIONS All

8.2.5 VpGetLineState()

SYNTAX vpStatusType

VpGetLineState(
    VpLineCtxType *pLineCtx, /* Pointer to line context */
    VpLineStateType *pCurrentState) /* Ptr to store line state */ 

DESCRIPTION This function retrieves the current state of the specified line. The line state is written to the location pointed to by pCurrentState. VpSetLineState(), on page 90 describes the line states.

RETURNS See VP-API-II Function Return Type. on page 10

EVENTS GENERATED None

DEVICES All

TERMINATIONS All

8.2.6 VpFlushEvents()

SYNTAX vpStatusType

VpFlushEvents(
    VpDevCtxType *pDevCtx) /* Pointer to device context */ 

DESCRIPTION This function empties the VP-API-II event queue. This function does not clear the VP-API-II results buffer; it only clears the pending event queue.

RETURNS See VP-API-II Function Return Type, on page 10

EVENTS GENERATED None

DEVICES All

TERMINATIONS All

8.2.7 VpGetResults()

SYNTAX vpStatusType

VpGetResults(

VpEventType *pEvent, /* Ptr to event that was filled by VpGetEvent() */

void *pResults) /* Pointer to buffer for the results */

DESCRIPTION

This function retrieves data associated with an event. Recall from Chapter 5 that events with attached results have their hasResults members set to TRUE. The application must either read the results using VpGetResults() or discard the results by calling VpClearResults().

To read results from the VTD, the application must allocate a buffer large enough to hold the result structure, then call this function with a pointer to that buffer. To ensure that the buffer is large enough regardless of the result type, the application can use VpResultsType, which is a union of all possible result types.

This function copies the result data into the application's buffer and frees the VP-API-II result buffer. The function uses the pEvent argument to determine what type of results are being copied. The application should simply pass a pointer to the same event returned by VpGetEvent(). Table 8-3 lists all VP-API-II functions that generate results along with the corresponding event ID and results data type.

Table 8-3 VP-API-II Functions with Extended Results

Function Event ID	Result Type
VpSetRelGain() VP_LINE_EVID_GAIN_CMP VpRelGainResultsType
VpLowLevelCmd16() VP_LINE_EVID_LLCMD_RX_CMP uint8p
VpGetLoopCond()	VP_LINE_EVID_RD_LOOP	VpLoopCondResultsType
VpGetOption()	VP_LINE_EVID_RD_OPTION	SeeSection 8.2.4.
VpTestLine()	VP_LINE_EVID_TEST_CMP VpTestResultType
VpDeviceIoAccessExt() VP_DEV_EVID_IO_ACCESS_CMP VpDeviceIoAccessExtType
VpLineIoAccess()	VP_LINE_EVID_LINE_IO_RD_CMP	VpLineIoAccessType

Notes:

1. The application can also use this function to determine the type of result data waiting in the result buffer. To use this mode of operation, this function should be called with the pResults argument equal to VP_NULL. When VpGetResults() is called in this mode, it overwrites the eventCategory and eventId members of the event structure passed to this function. Note that the event passed to this function must contain a valid deviceId and device context pointer (pDevCtx). If there are no results waiting in the buffer, the eventId member in event structure (pEvent) is overwritten with all zeros.

2. When reading options using VpGetOption(), the application can use the eventdata member of the event structure (VpEventType) to determine the option type (VpOptionIdType) that was read.

RETURNS

See VP-API-II Function Return Type, on page 10

EVENTS

GENERATED

None

DEVICES All

TERMINATIONS All

8.2.8 VpClearResults()

SYNTAX VpStatusType

VpClearResults(

VpDevCtxType *pDevCtx) /* Pointer to device context */

DESCRIPTION

This function clears the VP-API-II results buffer, thereby making room for more results. The application can call this function instead of VpGetResults() if it does not care about the results associated with an event.

The VP-API-II results queue provides access to only one result. In other words, calling this function deletes only the top results queue entry. This function can be called even when there are no outstanding results in the queue, in which case it simply returns VP_STATUS_SUCCESS.

RETURNS

See VP-API-II Function Return Type, on page 10

EVENTS

GENERATED

None

DEVICES All

TERMINATIONS All

8.2.9 VpGetDeviceStatusExt()

SYNTAX vpStatusType

VpGetDeviceStatusExt(
    VpDevCtxType *pDevCtx, /* Pointer to device context */
    VpDeviceStatusType *pDeviceStatus)    /* Struct containing parameters and results. */ 

DESCRIPTION This function accepts a pointer to a VpDeviceStatusType struct:

typedef struct {
    VpInputType input;
    uint8 status[VP_LINE_FLAG_BYTES];
} VpDeviceStatusType; 

It returns the status of the requested input for all lines controlled by the device. Each bit in the status field represents the status of input for one line. Information returned for invalid lines should be ignored.

The number of array elements, VP_LINE_FLAG_BYTES, is 1 for VE792 devices. The LSB represents channel 0; the MSB represents channel 7.

Refer to VpGetLineStatus(), on page 110 for the type definition of the input argument and for information on decoding the status flags.

Notes:

1. An active ground-key may be considered a fault by the application when the line is not employed in a ground-start system.
2. This function returns the status for all lines multiplexed into an array of eight-bit results. VpGetLineStatus() returns a boolean result for one specific line.

RETURNS

See VP-API-II Function Return Type, on page 10

EVENTS

GENERATED

None.

DEVICES VCP2, VE792

TERMINATIONS All

8.2.10 VpQuery()

SYNTAX vpStatusType

VpQuery(
    VpLineCtxType *pLineCtx, /* Pointer to line context */
    VpQueryIdType queryId    /* Type specifying information to query */
    uint16 handle)    /* Handle value returned with event */

DESCRIPTION This function is similar to VpGetLineStatus() (see page 110) but provides information that is non-boolean in nature about a particular line. The queryId information that can be requested is defined in the VpQueryIdType enumeration:
    typedef enum {
    VP_QUERY_ID_TEMPERATURE,    /* SLAC temperature */
    VP_QUERY_ID_METER_COUNT,    /* number of metering pulses sent */
    VP_QUERY_ID_LOOP_RES,    /* loop resistance */
    } VpQueryIdType;
This function generates the VP_LINE_EVID_QUERY_CMP event with event.hasResults value set to TRUE (indicating results are pending). The application then must call VpGetResults() to receive the data into a struct of type VpQueryResultsType. See VP_LINE_EVID_QUERY_CMP, on page 69 for a description of this type.

RETURNS See VP-API-II Function Return Type, on page 10
EVENTS GENERATED VP_LINE_EVID_QUERY_CMP, on page 69 

DEVICES VCP2-792, VE792, MeLT
TERMINATIONS All

9.1 OVERVIEW

This chapter describes the VP-API-II line tests. These commands provide low-level access to the test features of the selected VTD. The VoicePath Test Library, a companion Microsemi software product, adds a higher layer of abstraction on top of these VP-API-II test primitives, and offers the following key features:

• Provides optimal default values for test input parameters that do not typically change at run-time, such as integration times, settling times, etc.
• Performs a complete high-level test by running several test primitives in sequence.
• Converts results from test primitives into real-world values that the application can readily use.

The VP-API-II test facilities described in this chapter are generally not intended for direct use by the application; the application should use the VoicePath Test Library instead. For this reason, the test primitive inputs, outputs, and algorithms are not described in complete detail in this chapter. Refer to the VoicePath Test Library User's Guide for a description of the application interface into the VoicePath Test Library.

All VP-API-II line test primitives are initiated through the VpTestLine() function described below.

9.1.1 VpTestLine()

SYNTAX vpStatusType

VpTestLine(
    VpLineCtxType *pLineCtx, /* Pointer to line context */
    VpTestIdType test, /* Selects the test to perform */
    const void *pArgs, /* Pointer to test input arguments */
    uint16 handle) /* Handle value returned with event */

DESCRIPTION This function starts a test on the line associated with pLineCtx. The test parameter determines which line test is executed and may be any of the values listed in Table 9-1. This function returns the VP_STATUS_INVALID_ARG error code if the application attempts to run a test that is not supported by the device under test. The pArgs variable is a generic pointer to the test's input arguments. The test-specific input arguments are described later in this chapter. Finally, the handle argument specifies the application handle that is passed back with the resulting test complete event.

RETURNS See VP-API-II Function Return Type, on page 10

EVENTS GENERATED VP_LINE_EVID_TEST_CMP, on page 70

DEVICES All

TERMINATIONS All 

9.1.2 Test Types

VpTestIdType defines the set of tests that VpTestLine() can perform. Table 9-1 lists all valid test names along with the applicable VTD configuration. Each test is described in detail later in this chapter.

Table 9-1 Line Testing Primitives

Test ID Devices Summary
VP_TEST_ID_PREPARE VCP, VE792, MeLT Prepare for a test sequence
VP_TEST_ID_CONCLUDE VCP, VE792, MeLT Conclude a test sequence
VP_TEST_ID_SET_SENSE_GAIN_792 VCP2-792, VE792, MeLT Set ILG and IMT gains high or low
VP_TEST_ID_OPEN_VDC	VCP, VE792, MeLT-VCP	Measure open DC voltage
VP_TEST_ID_OPEN_VAC	VCP, VE792, MeLT-VCP	Measure open AC voltage
VP_TEST_ID_DIFF_VAC	VCP, VE792, MeLT-VCP	Measure differential AC voltage
VP_TEST_ID_IDC	VCP, VE792, MeLT-VCP	Measure DC currents
VP_TEST_ID_DC_RLOOP	VCP, VE792, MeLT-VCP	Measure DC loop resistance
VP_TEST_ID_AC_RLOOP	VCP, VE792, MeLT-VCP	Measure AC loop impedance
VP_TEST_ID_HOOK_STATUS	VCP, VE792	Check hook status while in Test mode
VP_TEST_ID_ALT_REN VCP, VE792, MeLT Alternative method REN measurement
VP_TEST_ID_3ELE_RES VCP, VE792, MeLT-VCP		Measure 3-element insulation resistance offset from half-battery.
VP_TEST_ID_3ELE_CAP	VCP, VE792, MeLT-VCP	Measure 3-element capacitance
VP_TEST_ID_KEYPAD	VCP, VE792	Keypad DTMF and pulse dial test
VP_TEST_ID_ARB_1TONE	VCP, VE792, MeLT	Measure arbitrary single tone
VP_TEST_ID_DIALTONE	VCP, VE792	Detect and measure dial tone (inward test)
VP_TEST_ID_MONITOR_IV	VCP2-792, VE792, MeLT	Non-intrusive measurement of AC or DC voltage or current on the line.
VP_TEST_ID_3ELE_RES_VMID	VCP2-792, VE792, MeLT-VCP	Measure 3-element insulation resistance using offset from specified voltage.
VP_TEST_ID_SET_BATTERIES	VCP2-792, VE792, MeLT	Defines the battery selection to be used during line testing.
VP_TEST_ID_GEN_TEST	VCP2-792, VE792, MeLT	Generic Test - capable of “full” control over the VE792 toolbox.

9.1.3 Running Tests

Executing a line test is done by a sequence of calls to the VpTestLine() function. This sequence is done in the VoicePath Test Library, so it normally is not necessary to call VpTestLine() directly:

- Before any line test is performed, the Test Library must prepare the line for testing and reserve VTD resources for testing. This is done by calling the VpTestLine() function with VP_TEST_ID_PREPARE for the test argument. Eventually, the VP_LINE_EVID_TEST_CMP event occurs, with attached results indicating whether the line is ready for further testing.

- Once the line is prepared for testing, the Test Library can initiate line tests by calling VpTestLine() with appropriate test arguments. For each call to VpTestLine(), the VTD generates the VP_LINE_EVID_TEST_CMP event with attached results. The Test Library will check the result errorCode variable before interpreting any other result data.

- When the Test Library is finished performing line tests, it will reset the line to normal operation and free

the VTD test resources. This is done by calling the VpTestLine() function with VP_TEST_ID_CONCLUDE for the test argument.

9.1.4 Test Inputs

Each VP-API-II line test may take a unique type of input arguments. Therefore, VpTestLine() takes a generic (void) pointer to the test input arguments. The application must create and initialize an instance of the correct test input type before calling VpTestLine() to run a test. The input data type associated with each test is described along with the individual tests later in this chapter.

9.1.5 Test Outputs

All VP-API-II line tests return their results through the asynchronous event/result reporting mechanism described in Chapter 5. The vpTestResultType structure encapsulates all test results into a single data type, and is defined as follows:

typedef struct {
    VpTestIdType testId; /* Test identifier */
    VpTestStatusType errorCode; /* Error code if Test Failed */
    VpTestResultsUnionType result; /* Return Results Union */
} VpTestResultType; 

The testId field of the result type indicates the type of test that generated the results. The errorCode field indicates whether the test executed normally. If some error occurred, the errorCode field gives the application some indication as to why the test failed. The following error codes are defined:

Table 9-2 Line Test Error Codes

Test ID Summary
VP_TEST_STATUS_SUCCESS Test is complete and results are available.
VP_TEST_STATUS_LINE_NOT_READY	Line not in test mode (VP_TEST_ID_PREPARE not executed)
VP_TEST_STATUS_RESOURCE_NA Line testing resources not available
VP_TEST_STATUS_TESTING Test underway - not aborted
VP_TEST_STATUS_VOUT_OOR Voltage out-of-range
VP_TEST_STATUS_VAB_OOR A-B voltage is out-of-range
VP_TEST_STATUS_ILG_OOR Longitudinal current is out-of-range
VP_TEST_STATUS_VCM_OOR Common-mode voltage is out-of-range
VP_TEST_STATUS_IAHL_OOR	A lead current is out-of-range in resistance or capacitance test
VP_TEST_STATUS_IBHL_OOR	B lead current is out-of-range in resistance or capacitance test
VP_TEST_STATUS_IAHH_OOR	A lead current is out-of-range in resistance or capacitance test
VP_TEST_STATUS_IBHH_OOR	B lead current is out-of-range in resistance or capacitance test
VP_TEST_STATUS_VABHL_OOR	A-B voltage is out-of-range in resistance or capacitance test
VP_TEST_STATUS_IALL_OOR	A lead current is out-of-range in resistance or capacitance test
VP_TEST_STATUS_IBLL_OOR	B lead current is out-of-range in resistance or capacitance test
VP_TEST_STATUS_IA_OOR	A lead current is out-of-range
VP_TEST_STATUS_IB_OOR	B lead current is out-of-range
VP_TEST_STATUS_IMT_OOR Metallic current is out-of-range
VP_TEST_STATUS_IMT_DC_OOR	Metallic current (DC) is out-of-range
VP_TEST_STATUS_TIMEOUT Failed to complete test in specified time
VP_TEST_STATUS_ABORTED Test aborted
VP_TEST_STATUS_INTERNAL_ERROR	An internal VTD error occurred
VP_TEST_STATUS_NO_CONVERGENCE VP_TEST_ID_NULL_IGND test failed to converge
VP_TEST_STATUS_TEST_NOT_SUPPORTED Test not supported due to device configuration.
VP_TEST_STATUS_VTIPBIAS_OOR A lead bias is out of range in unbalanced tone test.
VP_TEST_STATUS_VRINGBIAS_OOR B lead bias is out of range in unbalanced tone test.
VP_TEST_STATUS_VMID_OOR Voltage out-of-range.
VP_TEST_STATUS_GAIN_OOR User Specified Gain is out of range.
VP_TEST_STATUS_VA_OOR A lead Voltage is out of range.
VP_TEST_STATUS_VB_OOR B lead Voltage is out of range.
VP_TEST_STATUS_IMTOFFSET_OOR Metallic current offset is out of range.
VP_TEST_STATUS_BUF_OVERFLOW Test would exceed the buffer storage available.

The VP_TEST_STATUS_SUCCESS error code indicates that the test executed normally and the associated results are valid. Error codes ending in "_OOR" (out-of-range) indicate that saturation occurred while measuring or calculating some test result. The out-of-range test result is still returned to the application, but the accuracy of the result is not guaranteed. All other error codes imply that an error occurred and the application should ignore the test results.

The VpTestResultType structure contains a C union (VpTestResultsUnionType) that consolidates the unique test result types into a single object. Each test returns its results in a particular element of this union. The result data type returned by each test is described along with the individual tests later in this chapter.

9.1.6 Test Restrictions

The VP-API-II line tests require processor resources such as computation time and memory, and physical resources such as HAL, System Services, SLIC, and SLAC facilities. Because of these resource requirements, only one line test can be executed at a time on a particular device.

9.2 DETAILS OF TEST PRIMITIVES

9.2.1 VP\_TEST\_ID\_PREPARE

DESCRIPTION

This command prepares the line for running one or more tests. The VTD saves the line's state, reserves test resources, and marks the line as being in Test mode. Test prepare must be performed before running any other line tests.

Hook-switch events are disabled while the line is in Test mode. The application can determine the hook-switch state by running the hook status (VP_TEST_ID_HOOK_STATUS) test described in Section 9.2.10. If different AC or DC profiles are applied to a line while it is in Test mode, these changes are lost when the line is removed from Test mode and the VTD restores the line to its pre-test state.

INPUTS

None (set pArgs to VP_NULL)

ERROR CODES • VP_TEST_STATUS_SUCCESS

- VP_TEST_STATUS_RESOURCE_NA - The line can not be put into Test mode because the line is already in Test mode or some test resource is unavailable (e.g. max number of lines already in Test mode for VTD or SLAC).

RESULT DATA None

DEVICES VCP, VE792, MeLT

9.2.2 VP\_TEST\_ID\_CONCLUDE

DESCRIPTION

This command removes the line from Test mode by restoring the line's state, releasing the test resources, and marking the line as being in Normal mode. The application should execute the test conclude command when it is done testing a particular line.

INPUTS

typedef struct {
    bool abortTest;
} VpTestConcludeType; 

The abortTest flag determines whether a currently running test is stopped without running to completion. If abortTest is TRUE, then any test currently running on the line is aborted and the line is returned to Normal mode. If abortTest is FALSE, then the line is returned to Normal mode only if no test is currently running on the line.

ERROR CODES

• VP TEST STATUS SUCCESS - No test was running and the line is no longer in Test mode.
• VP_TEST_STATUS_TESTING - A test was running and was not aborted. The application must execute test conclude again to remove the line from Test mode.
• VP_TEST_STATUS_ABORTED - A test was running and was aborted. This occurs if the application performs a test conclude with the abortTest flag set to TRUE. This event also occurs if the application calls a VP-API-II function that is capable of interrupting a test (e.g. VpCalCodec(),
  VpInitDevice(), or VpInitLine() while a test is running on a relevant line. In this case, the handle attached to the event is the same handle specified by the application when the interrupted test was started.
• VP_TEST_STATUS_LINE_NOT_READY - The specified line was not in Test mode.

RESULT DATA None

DEVICES VCP, VE792, MeLT

9.2.3 VP\_TEST\_ID\_SET\_SENSE\_GAIN\_792

DESCRIPTION

This command sets the A and B lead sense gain. This gain setting is only applied while the line is in Test mode. The sense gain is restored when the line is returned to Normal mode.

This command must be called before executing a test measuring an A-lead or B-lead parameter. The specified gain will not be changed by the test execution; multiple tests can be executed before setting the sensing gain again.

This command has no effect on VP TEST ID GEN TEST, on page 142, as that test primitive includes its own way of specifying the sensing gain.

INPUTS

typedef struct {
    Vp792SenseGainType senseGain;
} VpTestSet792SenseGainType;

Enumeration Data Type: Vp792SenseGainType:
    VP792_SENSE_GAIN_0DB_GAIN
    VP792_SENSE_GAIN_28DB_GAIN
    VP792_SENSE_GAIN_10DB_LOSS 

ERROR CODES • VP TEST STATUS SUCCESS

- VP_TEST_STATUS_TESTING
- VP_TEST_STATUS_LINE_NOT_READY

RESULT DATA None

DEVICES VCP2-792, VE792, MeLT

9.2.4 VP\_TEST\_ID\_OPEN\_VDC

DESCRIPTION

This test measures open-circuit DC voltage by placing the SLIC device in the Disconnect mode and measuring the loop voltage through the SLAC sense pins SA and SB. The usable range is limited to voltages between VBH and the higher of BGND or VBP unless the SLIC driver outputs AD and BD are also disconnected from the loop. For some line circuit termination types, the SLIC driver outputs can be disconnected from the loop by setting the relay state to Reset before executing this test. Other line circuit termination types may use a PTC that becomes high impedance under surge. See VpSetRelayState(), on page 93 for details. In this case, the usable range is limited by the secondary over-voltage protection element on the line circuit, or by the value of the RSA and RSB resistors.

INPUTS

typedef struct {
    bool calMode;
    uint16 integrateTime;
    uint16 settlingTime;
    VpTestTipSelectType tip;
} VpTestOpenVType; 

The calMode parameter modifies the behavior of this test. It is used by Microsemi's VP-API-II Test Library software. The application should set this variable to FALSE when calling this function directly.

The integrateTime parameter determines how long the loop voltage is integrated. The settlingTime parameter determines how long the device waits before starting integration. Both integrateTime and settlingTime are specified in units of 125 s. In addition to the settlingTime, the start of integration is further postponed by a filter delay, specified below. The sum of the integrateTime, settlingTime, and filter delay must be less than or equal to 4095.875 ms.

If calMode is FALSE the filter delay is 150 ms. If calMode is TRUE the filter delay is 0 ms.

The tip variable determines whether the tip lead (VP_TEST_TIP) or ring lead (VP_TEST_RING) is measured.

ERROR CODES • VP_TEST_STATUS_SUCCESS

• VP_TEST_STATUS_TESTING
- VP_TEST_STATUS_LINE_NOT_READY
• VP_TEST_STATUS_VOUT_OOR

RESULT DATA

int16 sVout;

The sVout result is a signed integer that must be converted to a real voltage.

DEVICES VCP, VE792, MeLT-VCP

9.2.5 VP\_TEST\_ID\_OPEN\_VAC

DESCRIPTION

This test measures open-circuit AC voltage by placing the SLIC device in the Disconnect mode and measuring the loop voltage through the SLAC sense pins SA and SB. The usable range is limited to voltages between VBH and the higher of BGND or VBP unless the SLIC driver outputs AD and BD are also disconnected from the loop. For some line circuit termination types, the SLIC driver outputs can be disconnected from the loop by setting the relay state to Reset before executing this test. Other line circuit termination types may use a PTC that becomes high impedance under surge. See VpSetRelayState(), on page 93 for details. In this case, the usable range is limited by the secondary over-voltage protection element on the line circuit, or by the value of the RSA and RSB resistors.

INPUTS

This test also uses the VpTestOpenVType structure described in VP_TEST_ID_OPEN_VDC, on page 125.

The calMode variable has no effect on this function and is ignored.

The integrateTime parameter determines how long the loop voltage is integrated. The settlingTime parameter determines how long the device waits before starting integration. Both integrateTime and settlingTime are specified in units of 125 s. In addition to the settlingTime, the start of integration is further postponed by a filter delay, specified below. The sum of the integrateTime, settlingTime, and filter delay must be less than or equal to 4095.875 ms.

The filter delay is always 150 ms for this test.

The tip variable determines whether the tip lead (VP_TEST_TIP) or ring lead (VP_TEST_RING) is measured.

ERROR CODES • VP_TEST_STATUS_SUCCESS

• VP_TEST_STATUS_TESTING
- VP_TEST_STATUS_LINE_NOT_READY
- VP_TEST_STATUS_VOUT_OOR

RESULT DATA

uint16 uvout;

The uVout result is an unsigned integer that must be converted to a real voltage.

This routine computes the RMS of the samples measured during the test. Note that a clipping error probably occurred if the RMS result exceeds 71% of the full scale range.

DEVICES VCP, VE792, MeLT-VCP

9.2.6 VP\_TEST\_ID\_DIFF\_VAC

DESCRIPTION

This test measures differential AC voltage by placing the SLIC device in the Disconnect mode and measuring the loop voltage through the SLAC sense pins SA and SB. The usable range is limited to voltages between VBH and the higher of BGND or VBP unless the SLIC driver outputs AD and BD are also disconnected from the loop. For some line circuit termination types, the SLIC driver outputs can be disconnected from the loop by setting the relay state to Reset before executing this test. Other line circuit termination types may use a PTC that becomes high impedance under surge. See VpSetRelayState(), on page 93 for details. In this case, the usable range is limited by the secondary over-voltage protection element on the line circuit, or by the value of the RSA and RSB resistors.

INPUTS

typedef struct {
    uint16 integrateTime;
    int16 gvsaCal;
    int16 gvsbCal;
    uint16 settlingTime;
} VpTestDiffVacType; 

The integrateTime parameter determines how long the loop voltage is integrated. The settlingTime parameter determines how long the device waits before starting integration. Both integrateTime and settlingTime are specified in units of 125 s. In addition to the settlingTime, the start of integration is further postponed by a filter delay, specified below. The sum of the integrateTime, settlingTime, and filter delay must be less than or equal to 4095.875 ms.

The filter delay is always 150 ms for this test.

The parameters gvsaCal and gvsbCal are gain correction factors used by Microsemi's VP-API-II Test Library software. These calibration factors are specified in signed 1.15 fixed-point format. The application should set these variables to zero when calling this function directly.

ERROR CODES • VP_TEST_STATUS_SUCCESS

- VP_TEST_STATUS_TESTING
- VP_TEST_STATUS_LINE_NOT_READY
- VP_TEST_STATUS_VOUT_OOR 

RESULT DATA

uint16 uVout;

The uVout result is an unsigned integer that must be converted to a real voltage.

This routine computes the RMS of the samples measured during the test. Note that a clipping error probably occurred if the RMS result exceeds 71% of the full scale range.

DEVICES VCP, VE792, MeLT-VCP

9.2.7 VP\_TEST\_ID\_IDC

DESCRIPTION

This test measures DC currents. During this test, the metallic voltage is set to zero and both leads are moved together by controlling the common-mode voltage. This creates a low impedance node that conducts any current caused by a foreign potential. Individual A and B lead currents are measured.

INPUTS

typedef struct {
    bool calMode;
    int16 vCm;
    uint16 integrateTime;
    uint16 settlingTime;
} VpTestIdcType; 

The calMode parameter modifies the behavior of this test. It is used by Microsemi's VP-API-II Test Library software. The application should set this variable to FALSE when calling this function directly.

The vCm parameter determines the common-mode voltage offset from half-battery applied during the test.

The integrateTime parameter determines how long the loop voltage is integrated. The settlingTime parameter determines how long the device waits before starting integration. Both integrateTime and settlingTime are specified in units of 125 s. In addition to the settlingTime, the start of integration is further postponed by a filter delay, specified below. The sum of the integrateTime, settlingTime, and filter delay must be less than or equal to 4095.875 ms.

If calMode is FALSE the filter delay is 150 ms. If calMode is TRUE the filter delay is 0 ms.

ERROR CODES • VP_TEST_STATUS_SUCCESS

• VP TEST STATUS TESTING
• VP TEST STATUS LINE NOT READY
• VP_TEST_STATUS_IA_OOR
• VP_TEST_STATUS_IB_OOR

RESULT DATA

typedef struct {
    int16 ia;
    int16 ib;
} VpTestResultVixType; 

The A lead current (ia) and B lead current (ib) results are signed integers that must be converted to real currents.

DEVICES VCP, VE792, MeLT-VCP

9.2.8 VP\_TEST\_ID\_DC\_RLOOP

DESCRIPTION

This test measures low value DC loop resistance by forcing a current and measuring the resulting voltage.

INPUTS

typedef struct {
    bool calMode;
    int16 iTestLevel;
    uint16 integrateTime;
    uint16 settlingTime;
} VpTestDcRLoopType; 

The calMode parameter modifies the behavior of this test. It is used by Microsemi's VP-API-II Test Library software. The application should set this variable to FALSE when calling this function directly.

The parameter iTestLevel defines the magnitude of the current generated during the test.

The integrateTime parameter determines how long the loop voltage is integrated. The settlingTime parameter determines how long the device waits before starting integration. Both integrateTime and settlingTime are specified in units of 125 μs. In addition to the settlingTime, the start of integration is further postponed by a filter delay, specified below. The sum of the integrateTime, settlingTime, and filter delay must be less than or equal to 4095.875 ms.

If calMode is FALSE the filter delay is 150 ms. If calMode is TRUE the filter delay is 0 ms.

ERROR CODES • VP TEST STATUS SUCCESS

- VP_TEST_STATUS_TESTING
- VP_TEST_STATUS_LINE_NOT_READY
- VP_TEST_STATUS_VAB_OOR
- VP_TEST_STATUS_ILG_OOR

RESULT DATA

typedef struct {
    int16 vab;
    int16 ilg;
    bool currentSaturation;
} VpTestResultDcRlType; 

The measured DC differential voltage is reported through the vab variable. The measured DC common-mode current is reported through the ilg variable.

Value currentSaturation is TRUE when the required current (iTestLevel) could not be delivered to the load, meaning the result for vab should be ignored.

DEVICES VCP, VE792, MeLT-VCP

9.2.9 VP\_TEST\_ID\_AC\_RLOOP

DESCRIPTION

This test measures AC loop impedance by applying a voltage to the line and measuring the resulting current.

INPUTS

typedef struct {
    bool calMode;
    uint16 freq;
    int16 vTestLevel;
    int16 vBias;
    uint16 integrateTime;
    uint16 settlingTime;
} VpTestAcRLoopType; 

The calMode parameter modifies the behavior of this test. It is used by Microsemi's VP-API-II Test Library software. The application should set this variable to FALSE when calling this function directly.

The freq parameter determines the frequency of the signal generated during the test, which must not be higher than 4000 Hz.

The vTestLevel parameter determines the amplitude of the signal generated during the test. The vBias parameter specifies the DC bias superimposed on the AC signal.

The integrateTime parameter determines how long the loop voltage is integrated. The settlingTime parameter determines how long the device waits before starting integration. Both integrateTime and settlingTime are specified in units of 125 s. In addition to the settlingTime, the start of integration is further postponed by a filter delay, specified below. The sum of the integrateTime, settlingTime, and filter delay must be less than or equal to 4095.875 ms.

If calMode is FALSE the filter delay is 150 ms. If calMode is TRUE the filter delay is 0 ms.

ERROR CODES • VP_TEST_STATUS_SUCCESS

- VP_TEST_STATUS_TESTING
- VP_TEST_STATUS_LINE_NOT_READY
- VP_TEST_STATUS_IMT_OOR
- VP_TEST_STATUS_ILG_OOR 

RESULT DATA

typedef struct {
    int16 imt;
    int16 ilg;
    int16 vab;
} VpTestResultAcRlType; 

The imt variable contains the measured RMS metallic current. The ilg variable contains the measured RMS AC common-mode current.

This routine computes the RMS of the samples measured during the test. Note that a clipping error probably occurred if the RMS result exceeds 71% of the full scale range.

The vab result is not used and should be ignored.

DEVICES VCP, VE792, MeLT-VCP

9.2.10 VP\_TEST\_ID\_HOOK\_STATUS

DESCRIPTION

This test returns the current state of the hook-switch for the specified line. Recall that hook-switch events are disabled for a line while it is in Test mode. This command provides a mechanism for checking the hook status between other line tests.

This function provides a method to restore the line AC and DC profiles and re-start DC feed operation after having performed one or more DMM-type line test and before executing any transmission test.

If the specified line is in Disconnect (VP_LINE_DISCONNECT) state or in the intermediate state following voltage, current, or impedance testing, then the line is ramped to the Standby state according to the relevant option (see VP_OPTION_ID_DCFEED_SLOPE, on page 46). The line state is then changed to VP_LINE_TALK and the DC feed function is restarted after completing the ramp to standby. The line status is sampled after the DC feed settling delay. During the sampling period the sense gains are set to their normal setting. The sense gains are restored to their previous settings when this test completes.

INPUTS

None (set pArgs to VP_NULL)

ERROR CODES • VP TEST STATUS SUCCESS

• VP_TEST_STATUS_TESTING
- VP_TEST_STATUS_LINE_NOT_READY

RESULT DATA

bool hstatus;

The hstatus flag indicates whether the line is off-hook (TRUE) or on-hook (FALSE).

DEVICES VCP, VE792

9.2.11 VP\_TEST\_ID\_ALT\_REN

DESCRIPTION

This test implements an alternative Ringer Equivalency Number (REN) measurement. This test measures the load capacitance present on the line by integrating the charging current following a voltage step. It is compatible with ringers equipped with back-to-back zener diodes if the voltage step is larger than twice the zener voltage.

INPUTS

typedef struct {
    uint16 integrateTime;
    int16 vDiff;
} VpTestRenType; 

The integrateTime parameter specifies the time over which to integrate the charging current. The integration time is specified in 125 s units. The application can specify an integration time from 0 to 2000 ms (0 to 16000).

The vDiff parameter determines the differential voltage applied to the line during this test.

The code performs a pre-charge step to condition the loop capacitance with a known charge before applying the step voltage. This pre-charge step is followed by a return to a 0 V differential condition before applying the voltage step used to measure the loop capacitance. Both pre-charge and 0 V dwell time durations are fixed at 150 ms.

ERROR CODES • VP TEST STATUS SUCCESS

- VP_TEST_STATUS_TESTING
- VP_TEST_STATUS_LINE_NOT_READY
- VP_TEST_STATUS_IMT_OOR
- VP_TEST_STATUS_IMT_DC_OOR 

RESULT DATA

typedef struct {
    int16 imt;
    int16 imtDc;
} VpTestResultRenType; 

The variable imt represent the capacitor charging current averaged over the integration period, and imtDc represents the line leakage current measured over an identical period under the full vDiff voltage.

DEVICES VCP, VE792, MeLT

9.2.12 VP\_TEST\_ID\_3ELE\_RES

DESCRIPTION

This test measures three-element insulation resistance.

INPUTS

typedef struct {
    bool calMode;
    int16 vCm;
    int16 vDiff;
    uint16 integrateTime;
    uint16 settlingTime;
} VpTestResType; 

The calMode parameter modifies the behavior of this test. It is used by Microsemi's VP-API-II Test Library software. The application should set this variable to FALSE when calling this function directly.

The vCm parameter determines the common-mode voltage offset from half-battery applied during the test.

The vDiff parameter determines the differential voltage applied during the test.

The integrateTime parameter determines how long the loop voltage is integrated. The settlingTime parameter determines how long the device waits before starting integration. Both integrateTime and settlingTime are specified in units of 125 s. In addition to the settlingTime, the start of integration is further postponed by a filter delay, specified below. The sum of the integrateTime, settlingTime, and filter delay must be less than or equal to 4095.875 ms.

If calMode is FALSE the filter delay is 150 ms. If calMode is TRUE the filter delay is 0 ms.

ERROR CODES • VP_TEST_STATUS_SUCCESS

- VP_TEST_STATUS_TESTING
- VP_TEST_STATUS_LINE_NOT_READY
- VP_TEST_STATUS_IAHL_OOR
- VP_TEST_STATUS_IBHL_OOR
- VP_TEST_STATUS_IAHH_OOR
- VP_TEST_STATUS_IBHH_OOR
- VP_TEST_STATUS_IALL_OOR
- VP_TEST_STATUS_IBLL_OOR
- VP_TEST_STATUS_VABHL_OOR 

RESULT DATA

typedef struct {
    int16 iahl;
    int16 ibhl;
    int16 iahh;
    int16 ibhh;
    int16 iall;
    int16 ibll;
    int16 vabh1;
} VpTestResultResType; 

The iahl, ibhl, iahh, ibhh, iall, and ibll variables report A lead and B lead currents measured at various phases of this test. The vabh1 variable reports the actual voltage between the A and B leads during the differential phase of this test.

DEVICES VCP, VE792, MeLT-VCP

9.2.13 VP\_TEST\_ID\_3ELE\_CAP

DESCRIPTION This test measures three-element capacitance.

INPUTS

typedef struct {
    bool calMode;
    int16 vCm;
    int16 vDiff;
    uint16 freq;
    int16 gimtCal;
    int16 gilgCal;
    uint16 integrateTime;
    uint16 settlingTime;
} VpTestCapType; 

The calMode parameter modifies the behavior of this test. It is used by Microsemi's VP-API-II Test Library software. The application should set this variable to FALSE when calling this function directly.

The vCm parameter determines the common-mode voltage offset from half-battery applied during the test.

The vDiff parameter determines the differential voltage applied during the test.

The freq parameter determines the frequency of the signal generated during the test, which must not be higher than 4000 Hz.

The parameters gimtCal and gilgCal are gain correction factors used by Microsemi's VP-API-II Test Library software. These calibration factors are specified in signed 1.15 fixed-point format. The application should set these variables to zero when calling this function directly.

The integrateTime parameter determines how long the loop voltage is integrated. The settlingTime parameter determines how long the device waits before starting integration. Both integrateTime and settlingTime are specified in units of 125 s. In addition to the settlingTime, the start of integration is further postponed by a filter delay, specified below. The sum of the integrateTime, settlingTime, and filter delay must be less than or equal to 4095.875 ms.

If calMode is FALSE the filter delay is 150 ms. If calMode is TRUE the filter delay is 0 ms.

ERROR CODES • VP TEST STATUS SUCCESS

- VP_TEST_STATUS_TESTING
- VP_TEST_STATUS_LINE_NOT_READY
- VP_TEST_STATUS_IAHL_OOR
- VP_TEST_STATUS_IAHH_OOR
- VP_TEST_STATUS_IBHH_OOR
- VP_TEST_STATUS_IALL_OOR
- VP_TEST_STATUS_IBLL_OOR
- VP_TEST_STATUS_VABHL_OOR 

RESULT DATA

typedef struct {
    int16 iahl;
    int16 iahh;
    int16 ibhh;
    int16 iall;
    int16 ibll;
    int16 vabhl;
} VpTestResultCapType;

The iahl, iahh, ibhh, iall, and ibll variables report A lead and B lead currents measured at various phases of this test. The vabhl variable reports the actual voltage between the A and B leads during the differential phase of this test.

This routine computes the RMS of the samples measured during the test. Note that a clipping error probably occurred if the RMS result exceeds 71% of the full scale range.

DEVICES VCP, VE792, MeLT-VCP

9.2.14 VP\_TEST\_ID\_KEYPAD

DESCRIPTION

This test performs a DTMF and/or pulse-digit test. It terminates and returns a result as soon as a single DTMF or pulse digit is decoded and measured (if requested), or if an on-hook is detected. This test must be restarted to check for additional digits.

All samples used in this test are processed through the SLAC device's 55 Hz notch filter and a high-pass DC-reject filter implemented in the VTD/API.

INPUTS

typedef struct {
    VpkeyTestType kTest;
    uint16 timeout;
    uint16 freq;
    int16 amp;
    uint16 fftSize;
    uint16 threshold;
    VpOptionPulseType pulseOpt;
    bool useBuffer;
} VpTestKeypadType; 

The kTest parameter determines what type of keypad test is performed and can take any of the values defined by the VpKeyTestType shown below.

Enumeration Data Type: VpKeyTestType:
VP_KEY_TEST_DTMF
VP_KEY_TEST_PULSE
VP_KEY_TEST_BOTH 

The timeout parameter controls the duration of the test, and is specified in 125 s units. The application can specify a test duration from 0 to 8191.875 ms (0 to 65535). If no DTMF or pulse digits are detected within this time a timeout error is reported.

The freq parameter determines the frequency of the signal generated during the test, which must not be higher than 4000 Hz.

The amp parameter determines the peak amplitude of the signal generated during the test.

If freq or amp is zero, no tone is output during the test. If an output tone is requested, the tone is stopped when the start of a DTMF tone or pulse digit is detected, or when the test times-out.

If a DTMF test is requested, the fftSize parameter determines the number of samples used in the FFT calculation for DTMF measurement. fftSize may be set to 0, 128, 256, 512, 1024, 2048, or 4096. If fftSize is zero, a simple DTMF detection is performed and only the DTMF digit number is reported. Otherwise, the DTMF digit is measured, and the frequency and amplitude of the two tones are reported with the test results.

When a FFT result is requested, the threshold parameter specifies the minimum RMS signal amplitude that must be observed over a 200 sample period before DTMF measurement begins. If threshold is set to zero, only a valid DTMF digit starts the measurement process.

If a DTMF signal is detected, it is not reported until the signal stops or time-out is reached. This feature helps avoid reporting long DTMF digits more than once when keypad tests are run back-to-back.

If a pulse dial test is requested, the pulse limits are specified through the same structure used for the pulse dial options. See VP_DEVICE_OPTION_ID_PULSE, on page 31 for the definition of the VpOptionPulseType structure used for the pulseOpt parameter.

The useBuffer parameter is currently not used for VE792 devices.

The line must be in an off-hook detection condition before beginning this test or it will return with VP_TEST_STATUS_LINE_NOT_READY.

ERROR CODES • VP_TEST_STATUS_SUCCESS

• VP_TEST_STATUS_TESTING
• VP_TEST_STATUS_LINE_NOT_READY
- VP_TEST_STATUS_TIMEOUT - No digit detected within the timeout period.

RESULT DATA

typedef struct {
    VpKeyTestResultType kTestResult;
    VpDigitType digit;
    uint16 lowFreq;
    uint16 lowAmp;
    uint16 highFreq;
    uint16 highAmp;
    uint16 fftSize;
    uint16 minBreak;
    uint16 maxBreak;
    uint16 aveBreak;
    uint16 pulsePerSec;
    bool hookFlashDet;
    uint16 hookFlashDuration;
    bool disconnectDet;
} VpTestResultKeyType; 

The kTestResult variable returns one of the following values:

- VP_KT_DTMF_DET - A DTMF digit was detected but no FFT measurement was taken. The digit result contains the decoded DTMF digit. If no DTMF digit is detected, the digit result contains VP_DIG_NONE. All other result fields should be ignored.

- VP_KT_DTMF_MES - A DTMF digit was detected and measured. The digit result contains the decoded DTMF digit. The lowFreq and lowAmp results contain the frequency and peak amplitude of the lower frequency tone. The highFreq and highAmp results contain the frequency and peak amplitude of the higher frequency tone. Both lowFreq and highFreq are reported in Hertz. The lowAmp and highAmp results are reported as integers that must be converted to real numbers. The fftSize variable reports the actual sample size of the FFT used to measure the DTMF signal, which may be less than the requested sample size if the signal ended before the requested sample size was reached.

- VP_KT_PULSE - A pulse digit, hook flash, or disconnect was detected and measured. Pulse test results are decoded as follows:

• Both hookFlashDet and disconnectDet are FALSE
  A pulse digit was detected. The digit result contains the decoded pulse digit. The minBreak, maxBreak, and aveBreak results contain integer values corresponding to the percentage of the break interval over the average pulse period. The pulsePerSec result contains an integer number representing 10 times the number of pulses per second detected.
• hookFlashDet is TRUE
  A hook-switch flash was detected. The hookFlashDuration variable contains the length of the hook-switch flash in 125 s units. The digit, minBreak, maxBreak, aveBreak, and pulsePerSec results should be ignored.
• disconnectDet is TRUE
  The phone was on-hook long enough to be considered disconnected. The digit, minBreak, maxBreak, aveBreak, pulsePerSec, and hookFlashDuration results should be ignored.

- VP_KT_THRESH_DET - No DTMF digit was decoded, but a signal of sufficient amplitude (larger than the specified threshold) was detected and a FFT measurement is returned as in VP_KT_DTMF_MES above.

DEVICES VCP, VE792

9.2.15 VP\_TEST\_ID\_ARB\_1TONE

DESCRIPTION This test measures an arbitrary single tone.

The SLAC device's internal high-pass filter and 55 Hz notch filters are enabled during this test to remove any contribution from external induction noise. The filtered signal is passed to the API as linear PCM samples. The API waits for the signal strength to exceed a user-defined threshold, then starts collecting samples for FFT processing. The measured frequency and amplitude are returned to the application.

The line circuit termination impedance is typically set to 900 or 600 ohms flat to correlate with results from a transmission test set. The termination impedance coefficients are a function of the external hardware components and are not known to the VTD. The VTD can not automatically change the termination impedance coefficients. The application should set the desired termination impedance before executing this test.

INPUTS

typedef struct {
    uint16 timeout;
    uint16 fftSize;
    uint16 threshold;
    bool useBuffer;
} VpTestArblToneType; 

The timeout parameter controls the duration of the test, and is specified in 125 s units. The application can specify a test duration from 0 to 8191.875 ms (0 to 65535). If the API fails to detect a tone of sufficient strength within this time a timeout error is reported.

The fftSize parameter determines the number of samples used in the FFT calculation for tone measurement. fftSize may be set to 0, 128, 256, 512, 1024, 2048, or 4096.

The RMS signal amplitude must be greater than threshold over two consecutive 200-sample (25 ms) windows to trigger tone measurement. Once the signal meets the threshold requirement, the API starts collecting samples for tone measurement. If the tone drops below the threshold for any 200-sample (25 ms) window, the API stops collecting samples and returns to the initial state wherein it waits for the tone to meet the required threshold over a 400 sample window. If the signal strength remains above the threshold for fftSize samples, the FFT is performed and results are returned.

The useBuffer parameter is currently not used for VE792 devices.

ERROR CODES • VP_TEST_STATUS_SUCCESS

- VP_TEST_STATUS_TESTING
- VP_TEST_STATUS_LINE_NOT_READY
- VP_TEST_STATUS_TIMEOUT - The API did not detect a tone of sufficient strength for at least fftSize + 400 samples. 

RESULT DATA

typedef struct {
    uint16 rmsPwr;
    uint16 highFreq;
    uint16 highAmp;
    uint16 secFreq;
    uint16 secAmp;
    uint16 thdFreq;
    uint16 thdAmp;
} VpTestResultToneType; 

This test returns its results through a structure that is also used in VP_TEST_ID_DIALTONE, on page 138. Only the highFreq and highAmp variables in VpTestResultToneType are applicable to this test. highFreq reports the measured frequency of the tone in Hertz. highAmp reports the peak amplitude of the tone as an integer.

DEVICES VCP, VE792, MeLT

9.2.16 VP\_TEST\_ID\_DIALTONE

DESCRIPTION

This test starts dial tone detection and measurement.

All samples used in this test are processed through the SLAC device's 55 Hz notch filter and a high-pass DC-reject filter implemented in the VTD/API.

INPUTS

typedef struct {
    bool inward;
    uint16 timeout;
    uint16 detectGran,
    uint16 threshold;
    uint16 fftSize;
    uint16 duration;
    bool useBuffer;
} VpTestDialToneType; 

The inward parameter determines whether an inward (TRUE) or normal (FALSE) dial tone measurement is performed. During inward testing, the line circuit is configured as a high-impedance signal meter and measures the dial tone signal produced by another line. The application is responsible for connecting this line to the line under test before running an inward dial tone test.

During normal dial tone testing, the dial tone originates from the same line circuit as the one performing the test. Unlike other tests, this test does not interfere with normal hook event reporting, which allows the call processing application to request and obtain dial tone in the usual manner. This function only monitors dial tone presence and does not generate a substitute signal.

The timeout parameter limits the overall length of this test, and is specified in 125 s sample periods. A timeout error occurs if no tone was detected within the threshold, detectGran, and duration criteria discussed below.

The detectGran parameter defines the window size used to declare the tone detection event (VP_LINE_EVID_DTONE_DET) and loss-of-tone detection event (VP_LINE_EVID_DTONE_LOSS). The window size is specified in 125 μs sample periods. The tone detection event occurs when the RMS signal amplitude is greater than threshold for two consecutive tone detection window (detectGran) periods. FFT sample collection (re)starts when the tone detection event occurs. The loss-of-tone detection event occurs when the RMS signal amplitude falls below the threshold for one tone detection window (detectGran) period. FFT sample collection stops when the loss-of-tone detection event occurs. Note that the elapsed time since the start of the test, measured in 125 μs sample periods, is returned with the dial tone detection/loss events.

The fftSize parameter determines the number of samples used in the FFT calculation for dial tone measurement. fftSize may be set to 128, 256, 512, 1024, 2048, or 4096. If fftSize is greater than duration, fftSize is reduced to the largest legal value that is less than or equal to duration.

The duration parameter, in addition to the detectGran parameter, specifies the minimum length of the tone that must be observed in order for this test to return a success result. The duration parameter is specified in 125 μs sample periods. The duration period starts when the tone detection event occurs, which is the same time that FFT sample collection starts. Thus, the FFT is calculated over the first fftSize samples received during the duration period. If the loss-of-tone detection event occurs before the end of the duration period, the test returns to its initial state wherein it looks for a tone. The duration period should be greater than or equal to fftSize, else the fftSize is adjusted as described above. The duration argument must be at least 128 samples long and may be up to 65535 samples (8191.875 ms) long. The total minimum duration of the test, assuming that a tone is immediately detected and measured, is 2 * detectGran + duration.

The useBuffer parameter is currently not used for VE792 devices.

ERROR CODES • VP TEST STATUS SUCCESS

• VP TEST STATUS TESTING
• VP_TEST_STATUS_LINE_NOT_READY
- VP_TEST_STATUS_TIMEOUT - The API did not detect a tone meeting the threshold, detectGran, and duration criteria. The rmsPwr result contains the largest measured RMS signal power. All other results should be ignored.

RESULT DATA

typedef struct {
    uint16 rmsPwr;
    uint16 highFreq;
    uint16 highAmp;
    uint16 secFreq;
    uint16 secAmp;
    uint16 thdFreq;
    uint16 thdAmp;
} VpTestResultToneType; 

The rmsPwr result returns the RMS power of the samples used to perform the FFT analysis. This routine computes the RMS of the samples measured during the test. Note that a clipping error probably occurred if the RMS result exceeds 71% of the full scale range.

The highAmp, secAmp, and thdAmp results report the peak amplitude of the three largest tones measured during the test. These tones are sorted by amplitude such that highAmp > secAmp > thdAmp. The amplitudes are reported as integers that must be converted to a real number in a useful scale.

The highFreq, secFreq, and thdFreq results report the measured frequencies (in Hertz) of the highAmp, secAmp, and thdAmp tones respectively.

DEVICES VCP, VE792

9.2.17 VP\_TEST\_ID\_MONITOR\_IV

DESCRIPTION

This test performs a non-intrusive measurement of AC or DC voltage on the line.

INPUTS

typedef struct {
    bool calMode;
    uint16 integrateTime;
    uint16 settlingTime;
    VpMonitorIvFilterType filterType;
    VpMonitorIvMeasurementType measurement;
} VpTestMonitorIvType; 

The calMode parameter specifies either a low pass filter (calMode = TRUE) or pass-through filter (calMode = FALSE), applicable only when filterType = VP_TEST_TYPE_DC.

The integrationTime parameter specifies length of time to integrate. Range is 0 to 65335 in units of 125us.

The settlingTime parameter specifies length of time to integrate. Range is 0 to 65335 in units of 125us.

The filterType parameter specifies either a DC or AC type filter to apply to the data.

Enumeration Data Type: VpMonitorIvFilterType:
VP_TEST_TYPE_DC /* Applies a low-pass filter and calculates the average */
VP_TEST_TYPE_AC /* Applies a high-pass filter and calculates the RMS value */ 

The measurement parameter specifies the physical quantity to measure. It can be one of the following:

Enumeration Data Type: VpMonitorIVMeasType:
VP_TEST_MEAS_VA
VP_TEST_MEAS_VB
VP_TEST_MEAS_VAB
VP_TEST_MEAS_IMT
VP_TEST_MEAS_ILG 

ERROR CODES • VP TEST STATUS SUCCESS

- VP_TEST_STATUS_TESTING
- VP_TEST_STATUS_LINE_NOT_READY
- VP_TEST_STATUS_GAIN_OOR 

RESULT DATA

int16 sVout;

The sVout result is a signed integer that must be converted to a real voltage or current. Full range of -32768 to 32767 is provided.

DEVICES VCP2-792, VE792, MeLT

9.2.18 VP\_TEST\_ID\_3ELE\_RES\_VMID

DESCRIPTION

This test measures three-element insulation resistance using offsets from the selected vMid voltage.

INPUTS

typedef struct {
    bool calMode;
    int16 vCm;
    int16 vDiff;
    uint16 integrateTime;
    uint16 settlingTime;
    int16 vMid;
} VpTestResVmidType; 

The calMode parameter modifies the behavior of this test. It is used by Microsemi's VP-API-II Test Library software. The application should set this variable to FALSE when calling this function directly.

The vCm parameter determines the common-mode voltage offset from half-battery applied during the test.

The vDiff parameter determines the differential voltage applied during the test.

The integrateTime parameter determines how long the loop voltage is integrated. The settlingTime parameter determines how long the device waits before starting integration. Both integrateTime and settlingTime are specified in units of 125 s. In addition to the settlingTime, the start of integration is further postponed by a filter delay, specified below. The sum of the integrateTime, settlingTime, and filter delay must be less than or equal to 4095.875 ms.

If calMode is FALSE the filter delay is 150 ms. If calMode is TRUE the filter delay is 0 ms.

The vMid parameter specifies the mid voltage to use during test. Range is -32768 to +32767 as needed at the D/A converter.

ERROR CODES • VP_TEST_STATUS_SUCCESS

- VP_TEST_STATUS_TESTING
- VP_TEST_STATUS_LINE_NOT_READY
- VP_TEST_STATUS_IAHL_OOR
- VP_TEST_STATUS_IBHL_OOR
- VP_TEST_STATUS_IAHH_OOR
- VP_TEST_STATUS_IBHH_OOR
- VP_TEST_STATUS_IALL_OOR
- VP_TEST_STATUS_IBLL_OOR
- VP_TEST_STATUS_VABHL_OOR
- VP_TEST_STATUS_VMID_OOR 

RESULT DATA

typedef struct {
    int16 iahl;
    int16 ibhl;
    int16 iahh;
    int16 ibhh;
    int16 iall;
    int16 ibll;
    int16 vabh1;
} VpTestResultResType; 

The iahl, ibhl, iahh, ibhh, iall, and ibll variables report A lead and B lead currents measured at various phases of this test. The vabh1 variable reports the actual voltage between the A and B leads during the differential phase of this test.

DEVICES VCP2-792, VE792, MeLT-VCP

9.2.19 VP\_TEST\_ID\_SET\_BATTERIES

DESCRIPTION

Sets the BSEL control bits of the Intrusive Test Drive State Configuration to get battery selection defined by bs0 and bs1 variables. Variable bs0 controls state of high battery switch, between VBL and VBH. Variable bs1 controls state of positive battery switch, between GND and VBP.

This function can be called before executing any DMM-type line test and defines the batteries that will be active during any subsequent test. The default battery selection is defined by VP_TEST_ID_PREPARE to be VBH and GND. It will remain so during the complete testing sequence unless it is changed by executing the VP_TEST_ID_SET_BATTERIES function.

INPUTS

typedef struct {
    VpSetBatteriesType bs0;
    VpSetBatteriesType bs1;
} VpTestSetBatteriesType;

Enumeration Data Type: VpSetBatteriesType:
VP_BS_LOW
VP_BS_HIGH 

Table 9-3 VP_TEST_ID_SET_BATTERIES Behavior

bs1 bs0 Battery Selection
VP_BS_LOW VP_BS_LOW	VBL and GND
VP_BS_LOW VP_BS_HIGH	VBH and GND
VP_BS_HIGH VP_BS_LOW	VBL and VBP
VP_BS_HIGH VP_BS_HIGH	VBH and VBP

ERROR CODES • VP_TEST_STATUS_SUCCESS

• VP TEST STATUS TESTING
- VP_TEST_STATUS_LINE_NOT_READY

RESULT DATA None.

DEVICES VCP2-792, VE792, MeLT

9.2.20 VP\_TEST\_ID\_GEN\_TEST

DESCRIPTION

This is a generic control over the VE792 test tools. This test provides low-level control over the testing functions such that it can be used as a building block to develop more elaborate testing algorithms. Most of the capabilities exposed in this test can be accessed using other tests. On the other hand, this test can be used to implement most other tests.

INPUTS

typedef struct {
    VpTestGenFilterType filter;
    VpTestMathType type;
    VpTestGenDriveType driveMode;
    VpTestGenSignalType signalMode;
    int16 vTestLevel;
    uint16 freq;
    int16 vTipBias;
    int16 vRingBias;
    uint16 integrateTime;
    uint16 settlingTime;
    VpTestGenGainType iaMeas;
    VpTestGenGainType vaMeas;
    VpTestGenGainType ibMeas;
    VpTestGenGainType vbMeas;
} VpTestGenTestType;

Enumeration Data Type: VpTestGenFilterType:
    VP_TEST_FILTER_LPF
    VP_TEST_FILTER_HPF
    VP_TEST_FILTER_NONE

Enumeration Data Type: VpTestMathType:
    VP_TEST_TYPE_AVG
    VP_TEST_TYPE_RMS
    VP_TEST_TYPE_DFT
    VP_TEST_TYPE_RAW

Enumeration Data Type: VpTestGenDriveType:
    VP_TEST_DRIVE_NONE
    VP_TEST_DRIVE_A
    VP_TEST_DRIVE_B
    VP_TEST_DRIVE_BOTH

Enumeration Data Type: VpTestGenSignalType:
    VP_TEST_SIGNAL_A
    VP_TEST_SIGNAL_B
    VP_TEST_SIGNAL_CM
    VP_TEST_SIGNAL_DIFF

Enumeration Data Type: VpTestGenGainType:
    VP_TEST_MEAS_LOW_GAIN
    VP_TEST_MEAS_NORM_GAIN
    VP_TEST_MEAS_HIGH_GAIN
    VP_TEST_MEAS_SKIP
    VP_TEST_MEAS_IMT_NORM_GAIN
    VP_TEST_MEAS_IMT_HIGH_GAIN
    VP_TEST_MEAS_VAB_LOW_GAIN
    VP_TEST_MEAS_VAB_NORM_GAIN
    VP_TEST_MEAS_VAB_HIGH_GAIN
    VP_TEST_MEAS_ILG_NORM_GAIN
    VP_TEST_MEAS_ILG_HIGH_GAIN 

The filter parameter selects the type of filtering performed by the SLAC test tool box onto the signal sampled by the SLAC A/D converter during the test. If filter is VP_TEST_FILTER_NONE, the filter delay is 0 ms. Otherwise, it is 150 ms.

The type parameter selects the math function performed by the SLAC test tool box onto the samples collected during the test.

The driveMode parameter determines the SLIC mode selected during the test.

The signalMode parameter determines the type of AC signal generated by the SLAC, amplified by the SLIC, and applied to the loop during the test.

The vTestLevel parameter determines the peak amplitude of the AC signal generated by the SLAC.

The freq parameter determines the frequency of the AC signal generated by the SLAC in tenths of Hertz.

The vTipBias and vRingBias parameters determine the tip and ring DC levels generated by the SLAC, amplified by the SLIC, and applied to the loop during the test.

The integrateTime parameter determines how many signal samples are included in the math function. The settlingTime parameter determines how long the device waits before starting the sample collection. Both integrateTime and settlingTime are specified in units of 125 μs. The sum of the integrateTime, settlingTime and filter delay must be less than or equal to 4095.875 ms.

The iaMeas, vaMeas, ibMeas, and vbMeas parameters select the signals that will be sampled by the SLAC A/D converter during the test. If set to VP_TEST_MEAS_LOW_GAIN, VP_TEST_MEAS_NORM_GAIN, or VP_TEST_MEAS_HIGH_GAIN the IA, VA, IB, and VB signals are sampled in low, normal, or high gain. If set to VP_TEST_MEAS_SKIP the respective signal is not measured.

• The iaMeas parameter can be set to the special values VP_TEST_MEAS_IMT_NORM_GAIN or VP_TEST_MEAS_IMT_HIGH_GAIN.
• The vaMeas parameter can be set to the special values VP_TEST_MEAS_VAB_LOW_GAIN, VP_TEST_MEAS_VAB_NORM_GAIN, or VP_TEST_MEAS_VAB_HIGH_GAIN.
• The ibMeas parameter can be set to the special values VP_TEST_MEAS_ILG_NORM_GAIN or VP_TEST_MEAS_ILG_HIGH_GAIN.

ERROR CODES • VP TEST STATUS SUCCESS

- VP_TEST_STATUS_TESTING
- VP_TEST_STATUS_LINE_NOT_READY
- VP_TEST_STATUS_IMT_OOR
- VP_TEST_STATUS_IMT_DC_OOR
- VP_TEST_STATUS_IMTOFFSET_OOR
- VP_TEST_STATUS_BUF_OVERFLOW
- VP_TEST_STATUS_IA_OOR
- VP_TEST_STATUS_IB_OOR
- VP_TEST_STATUS_VTIPBIAS_OOR
- VP_TEST_STATUS_VRINGBIAS_OOR 

RESULT DATA

typedef struct {
    int16 iaReal;
    int16 iaImag;
    int16 vaReal;
    int16 vaImag;
    int16 ibReal;
    int16 ibImag;
    int16 vbReal;
    int16 vbImag;
} VpTestResultsGenTestType; 

When using the option type = VP_TEST_TYPE_DFT, the test returns results in the real and imaginary format. Otherwise, magnitude only results are returned in the real values. On the FXS implementation, the absolute phase is arbitrary, but the relative phase difference between each of the 4 possible results is correct.

The option type = VP_TEST_TYPE_RAW, is not supported by VE792.

DEVICES VCP2-792, VE792, MeLT

10.1 OVERVIEW

The System Services layer provides critical section, timing and interrupt control functions. These functions are system-dependent and must be implemented specifically for each platform on which the VP-API-II is used. The following functions are included in the System Services layer.

• VpSysEnterCritical() – Blocks entry into a critical section of VP-API code through some user-defined method.
• VpSysExitCritical() – Marks the end of a VP-API critical code section.
• VpSysDebugPrintf() – Print mechanism used by VP-API-II Debug features.

10.2 VP-API-II REENTRANCY

Reentrancy of a program can be defined as that program's ability to support sharing by multiple users or separate process with a single copy of that program.

The VP-API-II supports reentrant application development. Reentrancy does not mean that a function always completes its intended action when called more than once simultaneously (reentered). Reentrancy means that a function can detect whether it has been reentered and either completes its intended action or returns an error notifying the caller that the function was not successful. In either case the behavior of the reentrant function must be consistent and well-defined.

The VP-API-II follows the strategy of enclosing all access to shared resources in critical sections. There are a few different types of shared resources in the VoicePath system that must be protected from simultaneous access: device objects, line objects, and device resources. Recall from Section 3–2 that device objects and line objects are data structures that retain state information for devices and lines respectively. VP-API-II functions that modify these objects are protected from reentrant execution with critical sections. Device resources are physical components or features of a device. Some device resources, such as the HBI or MPI, must also be protected from simultaneous access. This is also accomplished with critical sections.

Please see the following sections describing the required VpSysEnterCritical() and VpSysExitCritical() functions for more details about the use of critical sections in VP-API-II

10.3 FUNCTION DESCRIPTIONS

10.3.1 VpSysEnterCritical()

SYNTAX uint8

VpSysEnterCritical(

VpDeviceIdType deviceId, /* Selects the target device */

VpCriticalSecType criticalSecType) /* Indicates critical section type */

DESCRIPTION

This function protects critical sections of VP-API-II code from reentrant execution. The application developer must implement this function such that, for a given device, no VP-API-II functions can be called from another thread of execution while any thread is within a critical section. This is typically done by disabling appropriate interrupts or "taking" a task-blocking semaphore.

The deviceId argument indicates which device resource or object is being accessed during this critical section. In systems with more than one VTD attached to the host microprocessor, the application can use this information to limit the number of interrupts disabled or tasks blocked by semaphores to only those interrupts or tasks that are related to a specific device. In most implementations the deviceId argument can simply be ignored.

The criticalSecType argument specifies the type of critical section being entered, and may take one of the following values:

Enumeration Data Type: VpCriticalSecType: VP_HBI_CRITICAL_SEC

HBI critical sections occur around HBI transactions. HBI transactions must not be interrupted.

The return value of VpSysEnterCritical() is ignored.

Notes:

If the application is designed such that all VP-API-II calls are made from only one thread of execution, then this function can simply return immediately. That is, no critical section protection is actually required in this case.

RETURNS Don't care.

EVENTS

GENERATED

None

DEVICES All

TERMINATIONS All

10.3.2 VpSysExitCritical()

SYNTAX uint8

VpSysExitCritical(

VpDeviceIdType deviceId, /* Selects the target device */

VpCriticalSecType criticalSecType) /* Indicates critical section type */

DESCRIPTION

The VP-API-II calls this function at the end of a critical code section. This function should restore the critical section protection (interrupt, semaphore, etc.) state to its condition prior to the last VpSysEnterCritical() call. This is typically done by enabling appropriate interrupts or "giving" a task-blocking semaphore. See VpSysEnterCritical(), on page 146 for descriptions of the deviceId and criticalSecType input parameters.

The return value of VpSysEnterCritical() is ignored.

RETURNS Don't care.

EVENTS

None

GENERATED

DEVICES All

TERMINATIONS All

10.3.3 VpSysDebugPrintf()

SYNTAX int

VpSysDebugPrintf(

char *format, ...)

DESCRIPTION

This function is used by the Debug Functions described in Chapter 13, on page 155. It is a print mechanism used for the purposes of debug output and can be defined simply as "printf" or "printk". The return value is ignored.

RETURNS Don't care.

EVENTS

None

GENERATED

DEVICES All

TERMINATIONS

All

CHAPTER

11 HARDWARE ABSTRACTION LAYER

Microsemi.

11.1 OVERVIEW

The Hardware Abstraction Layer (HAL) defines functions for communicating with a target VTD through the HBI. These functions hide the details of the platform HBI hardware design from the VP-API-II. The customer must implement these functions as appropriate for their specific platform. Microsemi provides example implementations of these functions. The following functions are included in the HAL:

• VpHalHbiInit() – Performs platform-specific initialization of the HBI.
• VpHalHbiCmd() - Issues an HBI command.
• VpHalHbiWrite() – Performs HBI write transactions.
• VpHalHbiRead() – Performs HBI read transactions.

All HAL functions take a deviceId argument that identifies the target VTD. This argument is of type VpDeviceIdType, which is defined by the customer. The deviceId is part of the device object created by the application at initialization. Note that the VP-API-II does not access the deviceId; it merely passes the deviceId to the HAL functions when accessing the associated VTD. This feature is useful for addressing a specific VTD in systems where a single host microprocessor controls more than one VTD. This parameter may be ignored in designs with only one VTD per host microprocessor.

HBI transactions are atomic operations in that once an transaction starts on a particular device, it must complete before another transaction can start for the same device. The VP-API-II surrounds all HBI transactions with calls to VpSysEnterCritical() and VpSysExitCritical() to guarantee that they run without interruption from another HBI request on the same device. For more information please see Chapter 10, on page 145.

11.2 FUNCTION DESCRIPTIONS

11.2.1 VpHalHbilnit()

SYNTAX bool

VpHalHbiInit(

VpDeviceIdType deviceId) /* Device chip select identifier */

DESCRIPTION

This function prepares the system for communicating through the HBI. The deviceId argument indicates the target device. The HBI read and write functions should work after this function is successfully executed. VpHalHbiInit() should be well-behaved even if called more than once between system resets. This function is called from VpInitDevice() before sending the device firmware image through the HBI.

RETURNS

This function returns TRUE on success or FALSE if the initialization command could not be written to the device.

DEVICES All

TERMINATIONS All

11.2.2 VpHalHbiCmd()

SYNTAX bool

VpHalHbiCmd(

VpDeviceIdType deviceId, /* Device chip select identifier */

uint16 cmd) /* HBI Command word to be sent */

DESCRIPTION

This function sends a command word over the HBI that has no associated data words. The deviceId argument indicates the target device. The function accepts a command word through the cmd argument that is written to the VTD. The command word is always sent over the HBI in big-endian byte order. This function is responsible for byte-swapping the command word if necessary.

RETURNS

This function returns TRUE on success or FALSE if the command could not be written to the device.

DEVICES All

TERMINATIONS All

11.2.3 VpHalHbiWrite()

SYNTAX bool

VpHalHbiWrite(

VpDeviceIdType deviceId, /* Device chip select identifier */

uint16 cmd, /* Command to write to the device */

uint8 numwords, /* Number of data bytes to write - 1 */

uint16p pData) /* Pointer to the data to write */

DESCRIPTION

This function sends a command word and writes up to 256 data words over the HBI. The deviceId argument indicates the target device. It accepts a HBI command through the cmd argument. The command word is always sent over the HBI in big-endian byte order. This function is responsible for byte-swapping the command word if necessary.

The pData parameter points to an array of data words. The numwords argument indicates the length of the array pointed to by pData minus one. For example, if numwords is 255, then the actual number of words to transmit is 256. No byte-swapping of data words is necessary in this function as long as the device's HBI is configured in VpHalHbiInit() to match the byte order of the host microprocessor.

If the pData is equal to zero, then this function should behave as though pData were an array of zeroes.

RETURNS

This function returns TRUE on success or FALSE if the command/data could not be written to the device.

DEVICES All

TERMINATIONS All

11.2.4 VpHalHbiRead()

SYNTAX bool

VpHalHbiRead(

VpDeviceIdType deviceId, /* Device chip select identifier */

uint16 cmd, /* Command to write to the device */

uint8 numwords, /* Number of data words to read - 1 */

uint16p pData) /* Pointer to the buffer to store data */

DESCRIPTION

This function sends a command word and reads up to 256 data words over the HBI. The deviceId argument indicates the target device. It accepts a HBI command through the cmd argument. The command word is always sent over the HBI in big-endian byte order. This function is responsible for byte-swapping the command word if necessary.

The pData parameter points to a receive buffer for the data read from the device. The numwords argument specifies the number of words to read from the device minus one. No byte-swapping of data words is necessary in this function as long as the device's HBI is configured in VpHalHbiInit() to match the byte order of the host microprocessor.

RETURNS

This function returns TRUE on success or FALSE if the data could not be read from the device.

DEVICES

All

TERMINATIONS

All

12.1 OVERVIEW

This chapter discusses how the VP-API-II handles VTD interrupts. VP-API-II functions must be invoked in response to VTD hardware interrupts. Depending on the type of interrupt, the VP-API-II may update its internal state or carry out other actions.

The complexity of the VP-API-II interrupt service routines varies depending on the type of device(s) being controlled. Specifically, the interrupt service routines for CSLAC devices are significantly more complex than those for the VCP and VE792 devices. This is due to the fact that much of the real-time functionality implemented in the VP-API-II for CSLAC is actually implemented within the VCP and VE792 devices themselves. This version of the document describes only the VE792 device interrupt handling requirements.

12.2 THE EVENT QUEUE

The VE792 contains an event queue. The maximum number of events in the event queue depends on the device type:

Table 12-1 Event Queue Sizes

Device Event Queue Size
VE792 32

When the VE792 needs to report information asynchronously to the host processor, it puts an event into its event queue and alerts the host processor by setting its interrupt pin (INT_N) low. The host application then retrieves the event from the VE792 by calling VpGetEvent() (see Section 8.2.1).

Depending on the type of event, the host may need to call VpGetResults() to retrieve additional information associated with the event from the response mailbox (see Section 8.2.7).

If the host waits for too long without calling VpGetEvent(), the event queue may eventually overflow. In this case the oldest event in the queue is discarded, and the overflow condition is reported as a VP_DEV_EVID_EVQ_OFL_FLT event.

12.3 INTERRUPT PIN BEHAVIOR

The VE792 provides an active-low interrupt pin (INT_N) for communicating events to the host processor. While the event queue is empty, the interrupt pin remains high. When the VE792 puts an event into the queue, it pulls the interrupt pin low.

The host processor calls VpGetEvent() to receive an event from the event queue. This causes the interrupt pin to go high if there are no more interrupts in the queue. If there are more interrupts in the queue, the interrupt pin remains low until the queue is empty. This behavior is depicted in Figure 12–1.

Figure 12-1 Interrupt Pin Behavior

graph TD
    A["INT_N"] --> B["Events in queue 0.01"]
    B --> C["1"]
    C --> D["2"]
    D --> E["1"]
    F["New events"] --> G["VpGetEvent()"]
    style F stroke-dasharray: 5 5
    style G stroke-dasharray: 5 5

12.4 HANDLING INTERRUPTS FROM VE792 DEVICES

Applications using the VE792 devices need only call VpGetEvent() in response to interrupts.

VpGetEvent() processes one interrupt at a time and returns a VpEventType data structure to the application indicating the cause of the interrupt. In some cases, VpGetEvent() handles the interrupt itself and does not return an event to the application.

If VpGetEvent() returns TRUE, then the application should not wait for another interrupt before calling VpGetEvent() again. Instead, the application must call VpGetEvent() again immediately, until the VE792 device's event queue is empty.

The application may need to take further action after receiving an event. For example, the application may wish to change a line's state after receiving a hook event for that line. Note that most interrupt/event sources can be masked (disabled). Refer to VP_OPTION_ID_EVENT_MASK, on page 37 for details on masking events.

13.1 OVERVIEW

The VoicePath API-II source code includes many different types of debug output which customers can use to isolate problems with their application and/or system. Each type of output can be included/excluded at compile time. If included, the output can be enabled/disabled at run time using the VP_OPTION_ID_DEBUG_SELECT option.

13.2 TYPES OF DEBUG OUTPUT

The following types of debug output are supported:

Table 13-1 Debug Flags

Macro Description	Purpose
VP_DBG_ERROR Error messages		Most API functions display such a message when they return a value other than VP_STATUS_SUCCESS.
VP_DBG_WARNING Warning	messages	Reports behavior that is probably not what was intended.
VP_DBG_INFO Info messages		Gives status information during normal operation of complicated functions.
VP_DBG_API_FUNC	API function entry/exit messages	Displays a message each time an API function is called, and another message showing the return code when the function exits.
VP_DBG_API_FUNC_INT	Internal function entry/exit messages	Analogous to VP_DBG_API_FUNC messages, but applies to internal functions, not top-level API functions.
VP_DBG_HAL	Hardware Abstraction Layer messages	Shows the low-level device register accesses as they are performed by the API. Useful for Microsemi support personnel in helping to debug customer issues.
VP_DBG_SSL	System Services Layer messages	Displays function calls and result codes of customer-defined SSL functions.
VP_DBG_EVENT Event messages		Shows the values returned by VpGetEvent() and VpGetResults().
VP_DBG_TEST Line Test Primitives		Shows miscellaneous values used by VpTestLine().
VP_DBG_TEST_FUNC Line Test Primitives		Displays a message at specific steps within a line testing primitive.

The above macros are defined as bitmasks which can be ORed together to select any combination of debug output types. The macro VP_DBG_ALL is provided for selecting all debug output types.

13.3 DEBUG OUTPUT SELECTION AT COMPILE TIME

Debug output strings, and the code necessary for displaying them, can occupy a non-negligible amount of memory in some applications. Therefore, the VP-API-II provides the ability to exclude unwanted types of debug output at compile time.

Customers may want to compile in all types of debug output during initial development, but include less debug output in the final application. Or, if separate "production" and "debug" builds are maintained, a different selection of debug output may be specified in each.

The selection of debug output types at compile time is specified in the header files in the api_lib/ includes directory:

The VP_DEBUG option (in vp_api_cfg.h) applies to all types of debug output.

• If VP_DEBUG is undefined, then all debug output is compiled out.
• If VP_DEBUG is defined, then VP_CC_DEBUG_SELECT option selects which types of debug output will be included.

The VP_CC_DEBUG_SELECT option (in vp_api_cfg.h) can be defined as VP_DBG_ALL to include all types of debug output, or it can be defined as the bitwise OR of one or more of the debug selector values (Table 13-1). Any debug output types not included in the definition will be compiled out.

Any debug output that is excluded at compile time cannot be enabled at runtime.

13.4 DEBUG OUTPUT SPECIFICITY

For each type of debug output, the VP-API-II source code may generate line-specific, device-specific, or "non-specific" (not particular to any device or line) messages.

Line-specific messages apply to a single line in the system. For example, passing an invalid Profile argument to VpConfigLine() will generate a line-specific debug message.

If the line cannot be identified, or if the error message is logically not specific to a particular line, then a device-specific debug message will be generated.

If the device cannot be identified, a non-specific debug message will be generated. In some instances, a message may be clearly line-specific or device-specific, but the particular function in which it is generated does not have enough information to determine the line or device association. In such cases, the debug output is non-specific.

The run-time selection of line-specific debug output messages is stored in the Line Object. The device-specific selections are stored in the Device Object. The non-specific selections are stored in a global variable (vpDebugSelectMask) defined in vp_debug.c.

13.5 DEBUG OUTPUT SELECTION AT RUN TIME

At run time, the VP_OPTION_ID_DEBUG_SELECT option can be used to enable/disable debug output. Using this option, each type of debug output can be enabled/disabled per line, per device, or for non-specific output.

The pValue argument of VpSetOption() should be a pointer to a uint32 number. The value should be the bitwise OR of one or more debug output selectors (Table 13-1). Other debug output types will be disabled.

The other arguments to VpSetOption() determine the specificity of the debug output that is being enabled/disabled:

Table 13-2 Valid Parameter Combinations for VP_OPTION_ID_DEBUG_SELECT

pLineCtx pDevCtx Result
valid VP_NULL	Enables/disables line-specific debug output messages for the given line
VP_NULL valid	Enables/disables device-specific debug output messages for the given device
VP_NULL VP_NULL	Enables/disables non-specific debug output messages

It is important to note that the above three cases do not overlap in effect. I.e., enabling/disabling the device-specific debug output for a given device will have no effect on the line-specific debug output for lines of that device. Also, enabling/disabling non-specific debug output has no effect on device-specific or line-specific output.

The default value of the VP_OPTION_ID_DEBUG_SELECT option can be modified by setting the VP_OPTION_DEFAULT_DEBUG_SELECT macro in vp_api_cfg.h.

13.6 PORTABILITY CONCERNS

13.6.1 Static Variable Coherency

It has always been a major design goal of the VP-API-II to give customers complete freedom over memory allocation. To that end, all state variables are maintained in a Line Object or Device Object which can be allocated statically, dynamically ("malloc"), or on the stack.

To allow enabling/disabling debug output at run-time for "non-specific" events, the VP-API-II uses a statically-allocated global variable, of type uint32, called vpDebugSelectMask, located in vp_debug.c. This variable is modified by VpSetOption(VP_OPTION_ID_DEBUG_SELECT) when both the pLineCtx and pDevCtx arguments are VP_NULL. It is accessed every time a non-specific debug output message is generated to determine if the message will be displayed.

The vpDebugSelectMask variable is internal to the API, and it is not normally necessary to access it externally. However, problems can arise in multiprocessing environments where each process may have its own copy of all static variables. In such cases, it is important to restore this variable each time a new process is started, either by modifying it directly, or by calling VpSetOption().

13.6.2 VpSysDebugPrintf()

The VP-API-II routes all debug output through a customer-defined function: VpSysDebugPrintf(). This function should be declared in sys_service.h (discussed in Chapter 10). In the simplest case, the following definition is sufficient:

define VpSysDebugPrintf printf

Please note that this function may be called multiple times in displaying a single line of debug output. I.e., the argument will not always end in "\n". This may be important for systems in which prefixing, suffixing, or other handling of the output stream is done line-by-line.

13.6.3 ANSI X3.64 Colors

The VP-API-II uses ANSI X3.64 color codes to display each type of debug message in a different color. These codes work with all popular modern terminal programs. However, there are many cases in which it is desirable to exclude these extra characters from the debug output. To do so, undefined the VP_DEBUG_COLOR option in vp_debug.h.

13.6.4 Displaying VpDeviceIdType and VpLineIdType

Line-specific and device-specific debug output messages are prefixed by displaying the corresponding VpLineIdType or VpDeviceIdType struct. Since these are customer-defined types, it may not be appropriate to display them using a printf("%d") format specifier. If not, the display method can be changed by modifying the definitions of the VP_PRINT_DEVICE_ID and VP_PRINT_LINE_ID macros (located in vp_api_types.h).

Channel See Section 1.1.2

Codec Coder/Decoder

CSLAC Conventional Microsemi SLAC™ device. For a complete list of supported CSLAC products, please see Supported Hardware Configurations, on page 5.

Device See Section 1.1.2

DTMF Dual-Tone Multi Frequency

FXO Foreign eXchange Office interface. This is the plug on the phone that receives a Plain Old Telephone Service (POTS) signal, typically from a Central Office (CO) of the Public Switched Telephone Network (PSTN). An FXO interface points to the Telco office.

FXS Foreign eXchange Subscriber interface. This is the plug on the wall that delivers a POTS signal from the local phone company's CO and must be connected to subscriber equipment such as telephones, modems, or fax machines. An FXS interface points to the subscriber.

GPI General Purpose Parallel Interface. This is the VTD's generic parallel port interface for the host processor. It is one of two physical interfaces currently available for the Host Bus Interface (HBI).

GR-909 Telcordia specification for Fiber in the Local Loop. GR-909 specifications for metallic loop testing have become the testing guidelines for many short-loop applications.

HBI Host Bus Interface. This is the host's interface to the VTD.

ISR Interrupt Service Routine

LCAS Line Circuit Access Switch. LCAS devices are essentially solid-state relays designed for telephony applications.

Line See Section 1.1.2

MPI Micro-Processor Interface. The MPI is Microsemi's serial control interface for CSLAC devices.

NTR Network Timing Reference

Profile Profiles encapsulate application specific data including cadencing, tones, Caller ID parameters, etc.

ProfileWizard A Microsoft Windows application that creates and organizes VoicePath profiles, included in the VoicePath SDK.

PSTN Public Switched Telephone Network

SLAC™ Subscriber Line Access Circuit, a Microsemi trademark.

SLIC Subscriber Line Interface Circuit

SPI	Serial Peripheral Interface. This is a four wire serial control interface between the VTD and the host processor that electrically conforms to the Motorola SPI slave interface standard. It is one of two physical interfaces currently available for the HBI.
Subscriber Line	The analog telephone line connecting the subscriber to the PSTN. Subscriber line is synonymous with loop or local loop.
VoicePathTM API II (VP-API-II)	An Application Program Interface that provides access to Microsemi's VTDs via the HBI or MPI. It is the primary component of the VoicePath Software Development Kit (VP SDK).
VoicePathTM SDK (VP-SDK)	A collection of tools to assist in the development of software for Microsemi devices. The VP-API-II and ProfileWizard are components of the VP SDK.
VCP	Voice Control Processor. For a complete list of VCP products please see Supported Hardware Configurations, on page 5.
VTD	Voice Termination Device.

Table B-1 lists all VP-API-II functions, along with their input types, return type, applicable devices, and applicable termination types.

Note:

1. Termination type "All" means either all termination types supported by the applicable devices, or the termination type is not relevant to the function.

The page number of the complete function description is included for each function in Table B-1.

Table B-1 VoicePath™ API II Functions Summary

Function Name Arguments	Return Type Devices Terminations Page
System Configuration Functions
VpMakeDeviceObject	VpDeviceType deviceType,VpDeviceIdType deviceId,VpDevCtxType *pDevCtx, void *pDevObj	VpStatusType All All			21
VpMakeLineObject	VpTermType termType, uint8 channelId,VpLineCtxType *pLineCtx, void *pLineObj,VpDevCtxType *pDevCtx	VpStatusType All All			22
VpMakeDeviceCtx	VpDeviceType deviceType,VpDevCtxType *pDevCtx, void *pDevObj	VpStatusType All All			23
VpMakeLineCtx	VpLineCtxType *pLineCtx, void *pLineObj,VpDevCtxType *pDevCtx	VpStatusType All All			24
VpFreeLineCtx VpLineCtxType	*pLineCtx VpStatusType All All				25
VpGetDeviceInfo VpDeviceInfoInfoType	*pDeviceInfo VpStatusType All All				26
VpGetLineInfo VpLineInfoType	*pLineInfo VpStatusType All All				27
VpMapLineId	VpLineCtxType *pLineCtx, VpLineIdType lineId	VpStatusType All All			28
Initialization Functions
VpInitDevice	VpDevCtxType *pDevCtx,VpProfilePtrType pDevProfile,VpProfilePtrType pAcProfile,VpProfilePtrType pDcProfile,VpProfilePtrType pRingProfile,VpProfilePtrType pFxoAcProfile,VpProfilePtrType pFxoCfgProfile	VpStatusType All All			77
VpInitLine	VpLineCtxType *pLineCtx,VpProfilePtrType pAcProfile,VpProfilePtrType pDcFeedOrFxoCfgProfile,VpProfilePtrType pRingProfile	VpStatusType VE792, VCP All			79
VpConfigLine	VpLinectxType *pLineCtx,VpProfilePtrType pAcProfile,VpProfilePtrType pDcFeedOrFxoCfgProfile,VpProfilePtrType pRingProfile	VpStatusType All All			80
Function Name	Arguments	Return Type	Devices	Terminations	Page
VpCalCodec	VpLineCtxType *pLineCtx, VpDeviceCalType mode	VpStatusType All All			81
VpCalLine VpLineCtxType *pLineCtx VpStatusType All All					82
VpInitRing	VpLineCtxType *pLineCtx, VpProfilePtrType pCadProfile, VpProfilePtrType pCidProfile	VpStatusType VE792, VCP All			83
VpInitCid	VpLineCtxType *pLineCtx, uint8 length, uint8p pCidData	VpStatusType VE792, VCP All			85
VpInitMeter	VpLineCtxType *pLineCtx, VpProfilePtrType pMeterProfile	VpStatusType VE792, VCP All			86
VpInitProfile	VpDevCtxType *pDevCtx, VpProfileType type, VpProfilePtrType pProfileIndex, VpProfilePtrType pProfile	VpStatusType VE792, VCP All			87
VpSetBatteries	VpLineCtxType *pLineCtx, VpBatteryModeType battMode, VpBatteryValuesType *pBatt	VpStatusType VCP, VE792, MeLT All			88
Control Functions
VpSetLineState	VpLinectxType *pLineCtx, VpLineStateType state	VpStatusType All All			90
VpSetLineTone	VpLinectxType *pLineCtx, VpProfilePtrType pToneProfile, VpProfilePtrType pCadProfile, VpDtmfToneGenType *pDtmfControl	VpStatusType VE792, VCP All			92
VpSetRelayState	VpLineCtxType *pLineCtx, VpRelayControlType rState	VpStatusType All All			93
VpSetRelGain	VpLineCtxType *pLineCtx, uint16 txLevel, uint16 rxLevel, uint16 handle	VpStatusType VE792, VCP All			94
VpSendSignal	VpLinectxType *pLinectx, VpSendSignalType signalType, void *pSignalData	VpStatusType VE792, VCP All			95
VpSendCid	VpLineCtxType *pLineCtx, uint8 length,VpProfilePtrType pCidProfile,uint8p pCidData	VpStatusType VE792, VCP All			96
VpContinueCid	VpLineCtxType *pLineCtx, uint8 length,uint8p pCidData	VpStatusType VE792, VCP All			97
VpStartMeter32Q	VpLineCtxType *pLineCtx, uint32_minDelay,uint32 onTime, uint32 offTime,uint16 numMeters, uint16 eventRate	VpStatusType VCP2-792, VE792 All			98
VpSetOption	VpLineCtxType *pLineCtx,VpDevCtxType *pDevCtx,VpOptionIdType option, void *pValue	VpStatusType All All			100
VpSetBFilter	VpLineCtxType *pLineCtx,VpBFilterModeType bFiltMode,VpProfilePtrType pAcProfile	VpStatusType	VCP-790, VCP2-792, VE792	All	101
VpLineIoAccess	VpLineCtxType *pLineCtx,VpLineIoAccessType *pLineIoAccess, uint16 handle	VpStatusType	VCP2, VE792,MeLT-VCP	All	102
VpDeviceIoAccessExt	VpDevCtxType *pDevCtx,VpDeviceIoAccessExtType *pDeviceIoAccess	VpStatusType	VCP2, VE792,MeLT-VCP	All	103
VpLowLevelCmd16	VpLineCtxType *pLineCtx, VpLowLevelCmdType cmdType, uint16 *writeWords, uint8 numWriteWordsd, uint8 numReadWords, uint16 handle	VpStatusType	VCP2-792, VE792,MeLT	All	104
VpGenTimerCtrl	VpLineCtxType *pLineCtx,VpGenTimerCtrlType timerCtrl, uint32 duration, uint16 handle	VpStatusType	VCP2-792, VE792,MeLT	All	106
Status and Query Functions
VpGetEvent	VpDevCtxType *pDevCtx, VpEventType *pEvent	bool	All	All	108
VpGetLineStatus	VpLinectxType *pLineCtx,VpInputType input, bool *pStatus	VpStatusType All All			110
VpGetLoopCond	VpLinectxType *pLineCtx, uint16 handle	VpStatusType	All	All	111
VpGetOption	VpLineCtxType *pLineCtx,VpDevCtxType *pDevCtx,VpOptionIdType option, uint16 handle	VpStatusType All All			112
VpGetLineState	VpLineCtxType *pLineCtx,VpLineStateType *pCurrentState	VpStatusType All All			113
VpFlushEvents VpDevCtxType	*pDevCtx VpStatusType All All				113
VpGetResults	VpEventType *pEvent, void *pResults	VpStatusType	All	All	114
VpClearResults VpDevCtxType	*pDevCtx VpStatusType All All				115
VpGetDeviceStatusExt	VpDevCtxType *pDevCtx, VpDeviceStatusType*pDeviceStatus	VpStatusType VCP2, VE792 All			116
VpQuery	VpLinectxType *pLineCtx,VpQueryIdType queryId, uint16 handle	VpStatusType	VCP2-792, VE792,MeLT	All	117
Testing Functions
VpTestLine	VpLinectxType *pLineCtx,VpTestIdType test, const void *pArgs,uint16 handle	VpStatusType All All			119
System Services Layer Functions
VpSysEnterCritical	VpDeviceIdType deviceId,VpCriticalSecType criticalSecTyp	uint8 All All			146
VpSysExitCritical	VpDeviceIdType deviceId,VpCriticalSecType criticalSecType	uint8 All All			147
VpSysDebugPrintf Variable	void All All				147
Hardware Abstraction Layer (HAL) Functions
VpHalHbiInit	VpDeviceIdType deviceId	bool	All	All	150
VpHalHbiCmd	VpDeviceIdType deviceId, uint16 cmd	bool	All	All	150
VpHalHbiWrite	VpDeviceIdType deviceId, uint16 cmd,uint8 numwords, uint16p pData	bool	All All		151
VpHalHoiRead	VpDeviceIdType deviceId, uint16 cmd,uint8 numwords, uint16p pData	bool	All All		151

Microsemi.

This appendix describes relay configurations for various line termination types. The relay states described in this section could be exercised using the function VpSetRelayState(), on page 93. Only those relay states that are described in this section are valid relay states for a given line termination types.

Figure C-1 VP_TERM_FXS_GENERIC

SLIC AD/BD SLIC SA/SB Test Load Tip/RingRelay State Bus VP_RELAY_NORMAL VP_RELAY_TALK VP_RELAY_BRIDGED_TEST

Figure C-2 VP_TERM_FXS_RR Termination

Relay StateBus	SLIC AD/BD	SLIC SA/SB	Test Load	Ringing	Tip/Ring
VP_RELAY_NORMAL (non-ringing)
VP_RELAY_NORMAL (ringing)
VP_RELAY_TALK
VP_RELAY_RINGING
VP_RELAY_BRIDGED_TEST
VP_RELAY_RESET(1)

(1) This relay state is used by some line testing functions. At the VpSetRelayState() command level, it has the same effect as the VP_RELAY_RINGING state. The VptlSysCaptureRingingBus() HTL function shall be used to isolate the ringing bus from the ringing generator before requesting the VP_RELAY_RESET state, otherwise ringing will get applied to the loop.

Figure C-3 VP_TERM_FXS_RR_TI Termination

(1) This relay state is used by some line testing functions. At the VpSetRelayState() command level, it has the same effect as the VP_RELAY_RINGING state. The VptlSysCaptureRingingBus() HTL function shall be used to isolate the ringing bus from the ringing generator before requesting the VP_RELAY_RESET state, otherwise ringing will get applied to the loop.

Figure C-4 VP_TERM_FXS_TI Termination

graph TD
    A["SLIC AD/BD SLIC SA/SB Test In TipsRing Relay State Bus"] --> B["VP_RELAY_NORMAL"]
    A --> C["VP_RELAY_TALK"]
    A --> D["VP_RELAY_TEST"]
    A --> E["VP_RELAY_DISCONNECT"]
    A --> F["VP_RELAY_BRIDGED_TEST"]
    A --> G["VP_RELAY_SPLIT_TEST"]
    B --> H["●"]
    C --> I["●"]
    D --> J["●"]
    E --> K["●"]
    F --> L["●"]
    G --> M["●"]
    H --> N["●"]
    I --> O["●"]
    J --> P["●"]
    K --> Q["●"]
    L --> R["●"]
    M --> S["●"]

Figure C-5 VP_TERM_FXS_RR_MW Termination

graph TD
    A["SLIC AD/BD SLIC SA/SB RINGING Tip/Ping"] --> B["State Bus"]
    B --> C["Message Waiting"]
    D["VP_RELAY_NORMAL (non-ringing)"] --> E["Line 1"]
    F["VP_RELAY_NORMAL (ringing)"] --> G["Line 2"]
    H["VP_RELAY_TALK"] --> I["Line 3"]
    J["VP_RELAY_RINGING"] --> K["Line 4"]
    L["VP_RELAY_BRIDGED_TEST"] --> M["Line 5"]
    N["VP_RELAY_LAMP_ON"] --> O["Line 6"]
    P["VP_RELAY_RESET"] --> Q["Line 7"]
    E --> R["End"]
    G --> R
    I --> R
    K --> R
    M --> R
    O --> R

REV 17: 13-SEP-2010

- Deleted all references to FXO.

REV 18: 29-OCT-2010

• Increased the number of valid profile table indexes from 15 to 32. See Profile Tables, on page 15.
• T h e VP_LINE_EVID_GEN_TIMER event is nonmaskable.
• Added Table 7–3, VpLowLevelCmd16() argument ranges, on page 157.

REV 19: 3-DEC-2010

- Added VP LINE EVID QUERY CMP, on page 100 and VpQuery(), on page 173.

REV 21: 31-MAR-2011

- For VCP2-792 and VE792 applications, VpSetBFilter() now accepts VP_PTABLE_NULL for pAcProfile regardless of the bFiltMode value.

REV 22: 31-MAY-2011

- New feature: The eventData field is now defined for VP LINE EVID FLASH, on page 60.

REV 24: 4-NOV-2011

- Replaced Zarlink trademarks and logos with Microsemi counterparts.

REV 25: 23-DEC-2011

- Added a description of interrupt pin behavior to Chapter 12, on page 153.

REV 26: 10-FEB-2012

• In VP_OPTION_ID_DCFEED_SLOPE, specified the value range for slopeLimit as 0 to 32767.
- In the VP_OPTION_ID_HOOK_DPTIC, The MODE more line states (in addition to VP_LINE_DISCONNECT and VP_LINE_DISABLED) now supported.

REV 27: 5-APR-2012

- The VP_LINE_RINGING_POLREV line state is identical to VP_LINE_RINGING. Updated VpSetLineState(), on page 90 accordingly.

REV 28: 5-MAR-2013

• Fixed an incorrect reference to VP_OPTION_ID_HOOK_DETECT_MODE in the VP_LINE_EVID_USER event section. This event is controlled by the VP_OPTION_ID_HOOK_DETECT_MODE option.
• The VP_OPTION_ID_HOOK_DETECTION(MODAssociated VP_LINE_EVID_USER event) now supports a new measurement type: VP_LOOP_COND_SELECTEDDBAT.
• Added note #5 into the VP_OPTION_ID_PULSE on page 45_.

REV 29: 25-APR-2013

• Added the VP TERM FXS RR MW termination to Chapter 1, on page 6.
• Added the relay bus Figure C-5 for the VP TERM FXS RR MW in Appendix C.
• Added the default relay states after initialization for the VP_TERM_FXS_RR_MW termination in the description of Section 6.2.1.

REV 30: 20-JUNE-2014

• Revised the description of the primitive VP TEST ID GEN TEST, on page 142.
• Various editorial corrections.

REV 31: FEBRUARY-2015

- No change.

REV 32: DECEMBER-2015

• Corrected the event type in the VpDeviceAccessExt() function.
• Added a note to the FXS RR and FXS RR TI relay tables.

REV 33: JULY-2016

• Editorial changes.
• Documented the VpGenTimerCtrl() function and the associated event.

Colorful abstract circular logo with interlocking curved segments (no text or symbols)

Microsemi®

Microsemi Corporate Headquarters

One Enterprise, Aliso Viejo, CA 92656 USA

Within the USA: [phone]

Outside the USA: [phone]

Sales: [phone]

Microsemi makes no warranty, representation, or guarantee regarding the information contained herein or the suitability of its products and services for any particular purpose, nor does Microsemi assume any liability whatsoever arising out of the application or use of any product or circuit. The products sold hereunder and any other products sold by Microsemi have been subject to limited testing and should not be used in conjunction with mission-critical equipment or applications. Any performance specifications are believed to be reliable but are not verified, and Buyer must conduct and complete all performance and other testing of the products, alone and together with, or installed in, any end-products. Buyer shall not rely on any data and performance specifications or parameters provided by Microsemi. It is the Buyer's responsibility to independently determine suitability of any products and to test and verify the same. The information provided by Microsemi hereunder is provided "as is, where is" and with all faults, and the entire risk associated with such information is entirely with the Buyer. Microsemi does not grant, explicitly or implicitly, to any party any patent rights, licenses, or any other IP rights, whether with regard to such information itself or anything described by such information. Information provided in this document is proprietary to Microsemi, and Microsemi reserves the right to make any changes to the information in this document or to any products and services at any time without notice.

Microsemi Corporation (Nasdaq: MSCC) offers a comprehensive portfolio of semiconductor and system solutions for communications, defense & security, aerospace and industrial markets. Products include high-performance and radiation-hardened analog mixed-signal integrated circuits, FPGAs, SoCs and ASICs; power management products; timing and synchronization devices and precise time solutions, setting the world's standard for time; voice processing devices; RF solutions; discrete components; security technologies and scalable anti-tamper products; Ethernet solutions; Power-over-Ethernet ICs and midspans; as well as custom design capabilities and services. Microsemi is headquartered in Aliso Viejo, Calif., and has approximately 3,600 employees globally. Learn more at www.microsemi.com.

Microsemi and the Microsemi logo are trademarks or are registered trademarks of Microsemi Corporation. All other trademarks and service marks are the property of their respective owners.

© 2016 Microsemi Corporation. All Rights Reserved

TECHNICAL DOCUMENTATION - NOT FOR RESALE