Google Git
Sign in
gfiber / barebox / mindspeed / 74944e8936cf3d873f6f16c17d15587a301240be / . / diags / proslic / proslic_api / proslic.h
blob: 95d8487fff51d10b026cb58a585e92cafe780704 [file] [log] [blame]
/*
** Copyright (c) 2007-2010 by Silicon Laboratories
**
** $Id: proslic.h 3100 2011-09-15 14:04:54Z cdp $
**
** Proslic.h
**
** Author(s):
** laj
**
** Distributed by:
** Silicon Laboratories, Inc
**
** This file contains proprietary information.
** No dissemination allowed without prior written permission from
** Silicon Laboratories, Inc.
**
** File Description:
** This is the header file for the ProSLIC driver.
**
** Dependancies:
** proslic_datatypes.h
**
*/
#ifndef PROSLIC_H
#define PROSLIC_H
/*include all the required headers*/
#include "../proslic_api_config.h"
#include "si_voice_datatypes.h"
#include "si_voice_ctrl.h"
#include "si_voice_timer_intf.h"
#include "si_voice.h"
/* UNSORTED ADDITIONS - These common parameters have been moved from
the drivers to here to support simultaneous compile of multiple devices
*/
/* Patch Parameters */
#define PATCH_JMPTBL_LOW_ADDR 82
#define PATCH_NUM_LOW_ENTRIES 8
#define PATCH_JMPTBL_HIGH_ADDR 1597
#define PATCH_NUM_HIGH_ENTRIES 8
#define PATCH_JMPTBL_START_ADDR 82
#define PATCH_NUM_ENTRIES 8
#define PATCH_MAX_SUPPORT_RAM 128
#define PATCH_MAX_SIZE 1024
/* BOM Constants */
#define BOM_KAUDIO_PM 0x8000000L
#define BOM_KAUDIO_NO_PM 0x3A2E8BAL
#define BOM_AC_ADC_GAIN_PM 0x151EB80L
#define BOM_AC_AC_GAIN_NO_PM 0x99999AL
#define FIXRL_VDC_SCALE 0xAE924B9L /** vdc sense scale when using fixed-rail */
/* Generic Constants */
#define COMP_5V 0x51EB82L
#define VBATL_13V 0xF00000L
#define COMP_10V 0xA3D705L
#define ZCAL_V_RASUM_IDEAL_VAL 0x8F00000L
#define ZCAL_DC_DAC_OS_VAL 0x1FFE0000L
/* MADC Constants */
#define SCALE_V_MADC 1074 /* 1/(1000*931.32e-9) mV */
#define SCALE_I_MADC 597 /* 1/(1e6*1.676e-9) uA */
/* Calibration Constants */
#define CAL_LB_CMDAC 0x0C
#define CAL_LB_TRNRD 0x03
#define CAL_LB_ALL 0x0F
#define TIMEOUT_MADC_CAL 100
#define TIMEOUT_GEN_CAL 300
#define TIMEOUT_LB_CAL 2410
/** @mainpage
* This document is a supplement to the ProSLIC API Specification. It has most
* of the APIs documented and hyperlinked.
*
* This document has the following tabs:
*
* - Main Page (this page) - introduction to the document.
* - Related pages - mainly the deprecated list is located here.
* Although these identifiers are present in the current release, they are
* targeted for deletion in a future release. Any existing customer code
* using deprecated identifiers should be modified as indicated.
* - Modules - this is the meat of the document - this has each functional group in outline format listed here.
* - Data Structures - This has every data structure listed in in the ProSLIC API in alphabetical order.
* - Files - this has the source files in hyperlink format. @note In some cases the hyperlink generator will not properly
* generate the correct reference or not be able to find it. In this case please use an alternative method.
*
*/
/** @defgroup PROSLIC_TYPES ProSLIC General Datatypes/Function Definitions
* This section documents functions and datastructures related to the
* ProSLIC/FXS chipsets.
* @{
*/
/*
* ----------------ProSLIC Generic DataTypes/Function Definitions----
**********************************************************************
*/
#define MAX_PROSLIC_IRQS 32 /**< How many interrupts are supported in the ProSLIC */
#define ON_HOOK_TIMEOUT 0x7f /**< Returned by @ref ProSLIC_DialPulseDetect() to
indicate a failure to detect a pulse digit */
/**********************************************************************/
/**
* @defgroup PROLSIC_BRD_DESIGN Board design settings
* @{
*/
/**
* Battery Rail option
*/
typedef enum
{
BO_DCDC_TSS, /**< Used for Fixed Rail DC-DC supplies */
BO_DCDC_TRACKING, /**< Used for Tracking DC-DC supplies */
BO_DCDC_EXTERNAL, /**< Used for external fixed rail supplies */
BO_DCDC_TSS_ISO, /**< Used for isolated TSS supplies */
BO_DCDC_FIXED_RAIL = BO_DCDC_TSS /**< Fixed rail replaced by TSS */
#ifndef SIVOICE_CFG_NEWTYPES_ONLY
,FIXED = BO_DCDC_FIXED_RAIL /**< @deprecated use BO_DCDC_FIXED_RAIL */
,TRACKING = BO_DCDC_TRACKING /**< @deprecated use BO_DCDC_TRACKING */
#endif
} batRailType;
/**
* Linefeed part number options - which front end is used.
*/
typedef enum {
SI3208,
SI3209,
SI3203,
SI3206,
SI3205,
SI3201,
SI3210_DISCRETE
} linefeed;
/** @} PROSLIC_BRD_DESIGN */
/**********************************************************************/
/**
* Map Proslic types to SiVoice types
*/
typedef SiVoiceControlInterfaceType controlInterfaceType; /**< Map ProSLIC to SiVoice type */
typedef SiVoiceControlInterfaceType proslicControlInterfaceType; /**< Map ProSLIC to SiVoice type */
typedef SiVoiceDeviceType ProslicDeviceType; /**< Map ProSLIC to SiVoice type */
typedef SiVoiceChanType proslicChanType; /**< Map ProSLIC to SiVoice type */
/**
* Define channel and device type pointers
*/
typedef ProslicDeviceType* proslicDeviceType_ptr; /**< Shortcut for pointer to a ProSLIC device type */
typedef proslicChanType *proslicChanType_ptr; /**< Shortcut for pointer to a ProSLIC channel type */
/** @} PROSLIC_TYPES */
/** @addtogroup PD_DETECT
* @{
*/
/**
* This is structure used to store pulse dial information
*/
typedef struct {
uInt8 currentPulseDigit;
void *onHookTime; /**< Timestamp for when the onhook detection occured */
void *offHookTime; /**< Timestamp for when the offhook detection occured */
} pulseDialType;
/**
* Defines structure for configuring pulse dial detection
*/
typedef struct {
uInt8 minOnHook; /**< Min mSec for onhook */
uInt8 maxOnHook; /**< Max mSec for onhook */
uInt8 minOffHook; /**< Min mSec for offhook */
uInt8 maxOffHook; /**< Max mSec for offhook */
} pulseDial_Cfg;
/** @} PD_DETECT */
/** @addtogroup PROSLIC_INTERRUPTS
* @{
*/
/**
* Interrupt tags
*/
typedef enum {
IRQ_OSC1_T1,
IRQ_OSC1_T2,
IRQ_OSC2_T1,
IRQ_OSC2_T2,
IRQ_RING_T1,
IRQ_RING_T2,
IRQ_PM_T1,
IRQ_PM_T2,
IRQ_FSKBUF_AVAIL, /**< FSK FIFO depth reached */
IRQ_VBAT,
IRQ_RING_TRIP, /**< Ring Trip detected */
IRQ_LOOP_STATUS, /**< Loop Current changed */
IRQ_LONG_STAT,
IRQ_VOC_TRACK,
IRQ_DTMF, /**< DTMF Detected - call @ref ProSLIC_DTMFReadDigit to decode the value */
IRQ_INDIRECT, /**< Indirect/RAM access completed */
IRQ_TXMDM,
IRQ_RXMDM,
IRQ_PQ1, /**< Power alarm 1 */
IRQ_PQ2, /**< Power alarm 2 */
IRQ_PQ3, /**< Power alarm 3 */
IRQ_PQ4, /**< Power alarm 4 */
IRQ_PQ5, /**< Power alarm 5 */
IRQ_PQ6, /**< Power alarm 6 */
IRQ_RING_FAIL,
IRQ_CM_BAL,
IRQ_USER_0,
IRQ_USER_1,
IRQ_USER_2,
IRQ_USER_3,
IRQ_USER_4,
IRQ_USER_5,
IRQ_USER_6,
IRQ_USER_7,
IRQ_DSP,
IRQ_MADC_FS,
IRQ_P_HVIC,
IRQ_P_THERM, /**< Thermal alarm */
IRQ_P_OFFLD
}ProslicInt;
/**
* Defines structure of interrupt data - used by @ref ProSLIC_GetInterrupts
*/
typedef struct {
ProslicInt *irqs; /**< Pointer of an array of size MAX_PROSLIC_IRQS (this is to be allocated by the caller) */
uInt8 number; /**< Number of IRQs detected/pending */
} proslicIntType;
/** @} PROSLIC_INTERRUPTS */
/** @addtogroup TONE_GEN
* @{
*/
/**
* Defines structure for configuring 1 oscillator - see your datasheet for specifics or use the configuration
* tool to have this filled in for you.
*/
typedef struct {
ramData freq;
ramData amp;
ramData phas;
uInt8 talo;
uInt8 tahi;
uInt8 tilo;
uInt8 tihi;
} Oscillator_Cfg;
/** @} TONE_GEN */
/*****************************************************************************/
/** @addtogroup SIGNALING
* @{
*/
/**
* Hook states - retruned by @ref ProSLIC_ReadHookStatus()
*/
enum {
PROSLIC_ONHOOK, /**< Hook state is onhook */
PROSLIC_OFFHOOK /**< Hook state is offhook */
};
#ifndef SIVOICE_CFG_NEWTYPES_ONLY
enum {
ONHOOK = PROSLIC_ONHOOK, /**< @deprecated- Please use PROSLIC_ONHOOK and PROSLIC_OFFHOOK for future code development */
OFFHOOK = PROSLIC_OFFHOOK
};
#endif
/** @} SIGNALING */
/*****************************************************************************/
/** @addtogroup PCM_CONTROL
* @{
* Loopback modes
*/
typedef enum {
PROSLIC_LOOPBACK_NONE, /**< Loopback disabled */
PROSLIC_LOOPBACK_DIG, /**< Loopback is toward the PCM side */
PROSLIC_LOOPBACK_ANA /**< Loopback is toward the analog side */
} ProslicLoopbackModes;
/**
* Mute options - which direction to mute
*/
typedef enum {
PROSLIC_MUTE_NONE = 0, /**< Don't mute */
PROSLIC_MUTE_RX = 0x1, /**< Mute toward the RX side */
PROSLIC_MUTE_TX = 0x2, /**< Mute toward the TX side */
PROSLIC_MUTE_ALL = 0x3 /**< Mute both directions */
} ProslicMuteModes;
/** @} PCM_CONTROL */
/*****************************************************************************/
/** @addtogroup GAIN_CONTROL
* @{
* Path Selector
*/
enum {
TXACGAIN_SEL = 0,
RXACGAIN_SEL = 1
};
/*
** Defines structure for configuring audio gain on the fly
*/
typedef struct {
ramData acgain;
uInt8 mute;
ramData aceq_c0;
ramData aceq_c1;
ramData aceq_c2;
ramData aceq_c3;
} ProSLIC_audioGain_Cfg;
/** @} GAIN_CONTROL */
/*****************************************************************************/
/** @addtogroup LINESTATUS
* @{
*/
/**
* enumeration of the Proslic polarity reversal states - used by ProSLIC_PolRev API
*/
enum {
POLREV_STOP, /**< Stop Polarity reversal */
POLREV_START, /**< Start Polarity reversal */
WINK_START, /**< Start Wink */
WINK_STOP /**< Stop Wink */
};
/**
* Defines initialization data structures
* Linefeed states - used in @ref ProSLIC_SetLinefeedStatus and @ref ProSLIC_SetLinefeedStatusBroadcast
*/
enum {
LF_OPEN, /**< Open circuit */
LF_FWD_ACTIVE, /**< Forward actvie */
LF_FWD_OHT, /**< Forward active, onhook transmission (used for CID/VMWI) */
LF_TIP_OPEN, /**< Tip open */
LF_RINGING, /**< Ringing */
LF_REV_ACTIVE, /**< Reverse battery/polarity reversed, active */
LF_REV_OHT, /**< Reverse battery/polarity reversed, active, onhook transmission (used for CID/VMWI) */
LF_RING_OPEN /**< Ring open */
} ;
/** @} LINESTATUS */
/*****************************************************************************/
/** @addtogroup GEN_CFG
* @{
*/
/**
* Defines initialization data structures
*/
typedef struct {
uInt8 address;
uInt8 initValue;
} ProslicRegInit;
typedef struct {
uInt16 address;
ramData initValue;
} ProslicRAMInit;
/**
* ProSLIC patch object
*/
typedef struct {
const ramData *patchData; /**< 1024 max*/
const uInt16 *patchEntries; /**< 8 max */
const uInt32 patchSerial;
const uInt16 *psRamAddr; /**< 128 max */
const ramData *psRamData; /**< 128 max */
} proslicPatch;
/** @} GEN_CFG */
/*****************************************************************************/
/** @addtogroup RING_CONTROL
* @{
*/
/**
* Ringing type options
* Ringing type options - Trapezoidal w/ a Crest factor CF11= Crest factor 1.1 or sinusoidal.
*/
typedef enum
{
ProSLIC_RING_TRAP_CF11,
ProSLIC_RING_TRAP_CF12,
ProSLIC_RING_TRAP_CF13,
ProSLIC_RING_TRAP_CF14,
ProSLIC_RING_TRAP_CF15,
ProSLIC_RING_TRAP_CF16,
ProSLIC_RING_SINE /***< Plain old sinusoidal ringing */
} ProSLIC_RINGTYPE_T;
/**
* Ringing (provisioned) object
*/
typedef struct
{
ProSLIC_RINGTYPE_T ringtype; /**< Is this a sinusoid or a trapezoidal ring shape? */
uInt8 freq; /**< In terms of Hz */
uInt8 amp; /**< in terms of 1 volt units */
uInt8 offset; /**< In terms of 1 volt units */
} ProSLIC_dbgRingCfg;
/** @} RING_CONTROL */
/*****************************************************************************/
/**
* Line Monitor - returned by @ref ProSLIC_LineMonitor
*/
typedef struct
{
int32 vtr; /**< Voltage, tip-ring in mV */
int32 vtip; /**< Voltage, tip-ground in mV */
int32 vring; /**< Voltage, ring-ground in mV */
int32 vbat; /**< Voltage, battery in mV */
int32 itr; /**< Loop current, in uA tip-ring */
int32 itip; /**< Loop current, in uA tip */
int32 iring; /**< Loop current, in uA ring */
int32 ilong; /**< Loop current, in uA longitudinal */
} proslicMonitorType;
/*****************************************************************************/
/** @addtogroup PROSLIC_DCFEED
* @{
*/
/**
* Powersave
*/
enum {
PWRSAVE_DISABLE = 0, /**< Disable power savings mode */
PWRSAVE_ENABLE = 1 /**< Enable power savings mode */
};
/**
** DC Feed Preset
*/
typedef struct {
ramData slope_vlim;
ramData slope_rfeed;
ramData slope_ilim;
ramData delta1;
ramData delta2;
ramData v_vlim;
ramData v_rfeed;
ramData v_ilim;
ramData const_rfeed;
ramData const_ilim;
ramData i_vlim;
ramData lcronhk;
ramData lcroffhk;
ramData lcrdbi;
ramData longhith;
ramData longloth;
ramData longdbi;
ramData lcrmask;
ramData lcrmask_polrev;
ramData lcrmask_state;
ramData lcrmask_linecap;
ramData vcm_oh;
ramData vov_bat;
ramData vov_gnd;
} ProSLIC_DCfeed_Cfg;
/** @} PROSLIC_DCFEED */
/*****************************************************************************/
/** @defgroup ProSLIC_API ProSLIC API
* proslic.c function declarations
* @{
*/
/*****************************************************************************/
/** @defgroup DIAGNOSTICS Diagnostics
* The functions in this group allow one to monitor the line state for abnormal
* situations.
* @{
*/
/**
* Test State - used in polled tests (such as PSTN Check)
*/
typedef struct
{
int32 stage; /**< What state is the test in */
int32 waitIterations; /**< How many iterations to stay in a particular state */
int32 sampleIterations; /**< How many samples have been collected */
}proslicTestStateType;
/**
* @brief
* This function allows one to monitor the instanteous voltage and
* loop current values seen on tip/ring.
*
* @param[in] pProslic - which channel should the data be collected from
* @param[in,out] *monitor - the data collected
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
*/
int ProSLIC_LineMonitor(proslicChanType_ptr pProslic, proslicMonitorType *monitor);
int32 ProSLIC_ReadMADCScaled(proslicChanType_ptr pProslic, uInt16 addr, int32 scale);
/** @defgroup PSTN_CHECK PSTN Check
* Monitor for excessive longitudinal current, which
* would be present if a live pstn line was connected
* to the port. To operate these sets of functions:
*
* - Iniitalize the PSTN object by calling @ref ProSLIC_InitPSTNCheckObj
* - Poll at a constant rate and call @ref ProSLIC_PSTNCheck. Check the return code of this function.
*
* Alternatively, you can call the DiffPSTNCheck versions of the above two functions.
*
* @note These functions may be disabled by doing a undef of @ref PSTN_DET_ENABLE in the configuration file.
* @{
*/
#define MAX_ILONG_SAMPLES 32 /**< How many samples to collect for PSTN check */
#define MAX_PSTN_SAMPLES 16 /**< Used in the PSTN check status code to indicate the number of samples to collect */
/**
* FEMF OPEN voltage test enable
*/
enum {
FEMF_MEAS_DISABLE, /**< Do not measure FEMF as part of PSTN Check */
FEMF_MEAS_ENABLE /**< Do measure FEMF as part of PSTN Check */
};
/** Standard line interfaces */
typedef struct
{
int32 avgThresh;
int32 singleThresh;
int32 ilong[MAX_ILONG_SAMPLES];
uInt8 count;
uInt8 samples;
int32 avgIlong;
BOOLEAN buffFull;
} proslicPSTNCheckObjType;
typedef proslicPSTNCheckObjType* proslicPSTNCheckObjType_ptr;
/** Re-Injection line interfaces (differential) */
typedef struct {
proslicTestStateType pState;
int dcfPreset1;
int dcfPreset2;
int entryDCFeedPreset;
uInt8 lfstate_entry;
uInt8 enhanceRegSave;
uInt8 samples;
int32 vdiff1[MAX_PSTN_SAMPLES];
int32 vdiff2[MAX_PSTN_SAMPLES];
int32 iloop1[MAX_PSTN_SAMPLES];
int32 iloop2[MAX_PSTN_SAMPLES];
int32 vdiff1_avg;
int32 vdiff2_avg;
int32 iloop1_avg;
int32 iloop2_avg;
int32 rl1;
int32 rl2;
int32 rl_ratio;
int femf_enable;
int32 vdiff_open;
int32 max_femf_vopen;
int return_status;
}proslicDiffPSTNCheckObjType;
typedef proslicDiffPSTNCheckObjType* proslicDiffPSTNCheckObjType_ptr;
/** @}PSTN_CHECK */
/** @}DIAGNOSTICS */
/*****************************************************************************/
/*
** proslic.c function declarations
*/
/** @defgroup PROSLIC_IF_CFG ProSLIC System control interface functions
* This group of functions is called for allocating memory and configuring the ProSLIC API to call specific control interfaces that the user implemented.
*
* @deprecated One should use the SiVoice equivalent functions. @ref SIVOICE_IF_CFG
* @{
*/
/*****************************************************************************/
/** @defgroup PROSLIC_MEMORY_IF ProSLIC Memory allocation/deallocation
* @deprecated One should use the SiVoice equivalent functions located: @ref SIVOICE_MEMORY_IF
* @{
*/
/**
* @brief
* Allocate memory and initialize the given structure.
*
* @param[in,out] **pCtrlIntf - the structure to initialize
*
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
* @deprecated Use @ref SiVoice_createControlInterface
*/
int ProSLIC_createControlInterface (controlInterfaceType **pCtrlIntf);
/**
* @brief
* Allocate memory and initialize the given structure.
*
* @param[in,out] **pDevice - the structure to initialize
*
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
* @deprecated Use @ref SiVoice_createDevice
*/
int ProSLIC_createDevice (ProslicDeviceType **pDevice);
/**
* @brief
* Allocate memory and initialize the given structure.
*
* @param[in,out] *hProslic - the structure to initialize
*
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
* @deprecated Use @ref SiVoice_createChannel
*/
int ProSLIC_createChannel (proslicChanType_ptr *hProslic);
/**
* @brief
* Destroys the given structure and deallocates memory.
*
* @param[in,out] *hProslic - the structure to initialize
*
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
* @deprecated Use @ref SiVoice_destroyChannel
*/
int ProSLIC_destroyChannel (proslicChanType_ptr *hProslic);
/**
* @brief
* Destroys the given structure and deallocates memory.
*
* @param[in,out] **pDevice - the structure to initialize
*
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
* @deprecated Use @ref SiVoice_destroyDevice
*/
int ProSLIC_destroyDevice (ProslicDeviceType **pDevice);
/**
* @brief
* Destroys the given structure and deallocates memory.
*
* @param[in,out] **pCtrlIntf - the structure to initialize
*
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
* @deprecated Use @ref SiVoice_destroyControlInterface
*/
int ProSLIC_destroyControlInterface (controlInterfaceType **pCtrlIntf);
/** @} PROSLIC_MEMORY_IF */
/*****************************************************************************/
/** @defgroup PROSLIC_IO ProSLIC SPI/GCI access routines
* This group of functions are used to associcate the transport mechanism (SPI, GCI) functions with the API. The actual
* functions being references are normally implemented by the customer for their particualr OS and platform.
*
* @deprecated One should use the SiVoice equivalent functions located: @ref SIVOICE_IO
* @{
*/
/**
* @brief
* Associate a interface object with a user supplied datastructure. This
* structure is passed to all the I/O routines that the ProSLIC API calls.
*
* @param[in,out] *pCtrlIntf - which interface to associate
* the user supplied structure with.
* @param[in] hCtrl - the user supplied structure.
*
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
* @deprecated Use @ref SiVoice_setControlInterfaceCtrlObj
*/
int ProSLIC_setControlInterfaceCtrlObj (controlInterfaceType *pCtrlIntf, void *hCtrl);
/**
* @brief
* Associate a interface object with the reset function.
*
* @param[in,out] pCtrlIntf - which interface to associate
* the user supplied function with.
* @param[in] Reset_fptr - the reset function pointer
*
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
* @deprecated Use SiVoice_setControlInterfaceReset
*/
int ProSLIC_setControlInterfaceReset (controlInterfaceType *pCtrlIntf, ctrl_Reset_fptr Reset_fptr);
/**
* @brief
* Associate a interface object with the register write function.
*
* @param[in,out] pCtrlIntf - which interface to associate
* the user supplied function with.
* @param[in] WriteRegister_fptr - the register write function pointer
*
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
* @deprecated Use SiVoice_setControlInterfaceWriteRegister
*/
int ProSLIC_setControlInterfaceWriteRegister (controlInterfaceType *pCtrlIntf, ctrl_WriteRegister_fptr WriteRegister_fptr);
/**
* @brief
* Associate a interface object with the register read function.
*
* @param[in,out] pCtrlIntf - which interface to associate the user supplied function with.
* @param[in] ReadRegister_fptr - the register read function pointer
*
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
* @deprecated Use @ref SiVoice_setControlInterfaceReadRegister
*/
int ProSLIC_setControlInterfaceReadRegister (controlInterfaceType *pCtrlIntf, ctrl_ReadRegister_fptr ReadRegister_fptr);
/**
* @brief
* Associate a interface object with the write RAM function.
*
* @param[in,out] pCtrlIntf - which interface to associate the user supplied function with.
* @param[in] WriteRAM_fptr - the reset function pointer
*
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
* @deprecated Use @ref SiVoice_setControlInterfaceWriteRAM
*/
int ProSLIC_setControlInterfaceWriteRAM (controlInterfaceType *pCtrlIntf, ctrl_WriteRAM_fptr WriteRAM_fptr);
/**
* @brief
* Associate a interface object with the read RAM function.
*
* @param[in,out] pCtrlIntf - which interface to associate
* the user supplied function with.
* @param[in] ReadRAM_fptr - the read RAM function pointer
*
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
* @deprecated Use @ref SiVoice_setControlInterfaceReadRAM
*/
int ProSLIC_setControlInterfaceReadRAM (controlInterfaceType *pCtrlIntf, ctrl_ReadRAM_fptr ReadRAM_fptr);
/** @} PROSLIC_IO */
/*****************************************************************************/
/** @defgroup PROSLIC_TIMER ProSLIC Timer functions
* This group of functions associates the customer supplied timer routines with the ProSLIC API.
* In most cases, only the delay function is needed. The other functions which are related
* to elapsed time can be set to NULL under this situation.
*
* @deprecated One should use the SiVoice equivalent functions located: @ref SIVOICE_TIMER
* @{
*/
/**
* @brief
* This function associates a timer object - which is user defined, but it is
* used with ALL channels of the particular control interface.
*
* @param[in] pCtrlIntf - which control interface to associate the given timer object with.
* @param[in] hTimer - the timer ojbect that is passed to all timer functions.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
* @sa SIVOICE_TIMER ProSLIC_setControlInterfaceDelay ProSLIC_setControlInterfaceTimeElapsed ProSLIC_setControlInterfaceGetTime
* @deprecated Use @ref SiVoice_setControlInterfaceTimerObj
*/
int ProSLIC_setControlInterfaceTimerObj (controlInterfaceType *pCtrlIntf, void *hTimer);
/**
* @brief
* Associate a timer delay function with a given control interface. The
* delay function takes in an argument of the timer object and the time in mSec
* and delays the thread/task for at least the time requested.
*
* @param[in] pCtrlIntf - which control interface to associate the function with.
* @param[in] Delay_fptr - the pointer to the delay function.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
* @sa SIVOICE_TIMER ProSLIC_setControlInterfaceTimerObj ProSLIC_setControlInterfaceTimeElapsed ProSLIC_setControlInterfaceGetTime
* @deprecated Use @ref SiVoice_setControlInterfaceDelay
*/
int ProSLIC_setControlInterfaceDelay (controlInterfaceType *pCtrlIntf, system_delay_fptr Delay_fptr);
/**
* @brief
* Associate a time elapsed function with a given control interface. The
* time elapsed function uses the values from the function specified in
* @ref SiVoice_setControlInterfaceGetTime and computes the delta time
* in mSec.
* @param[in] pCtrlIntf - which control interface to associate the function with.
* @param[in] timeElapsed_fptr - the pointer to the elapsed time function.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
* @sa SIVOICE_TIMER ProSLIC_setControlInterfaceTimerObj ProSLIC_setControlInterfaceDelay ProSLIC_setControlInterfaceGetTime
* @deprecated Use @ref SiVoice_setControlInterfaceTimeElapsed
*/
int ProSLIC_setControlInterfaceTimeElapsed (controlInterfaceType *pCtrlIntf, system_timeElapsed_fptr timeElapsed_fptr);
/**
* @brief
* Associate a time get function with a given control interface. The
* time get function returns a value in a form of a void pointer that
* is suitable to be used with the function specified in @ref SiVoice_setControlInterfaceTimeElapsed .
* This is typically used as a timestamp of when an event started. The resolution needs to be in terms
* of mSec.
*
* @param[in] pCtrlIntf - which control interface to associate the function with.
* @param[in] getTime_fptr - the pointer to the get time function.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
* @sa SIVOICE_TIMER ProSLIC_setControlInterfaceTimerObj ProSLIC_setControlInterfaceDelay ProSLIC_setControlInterfaceTimeElapsed
* @deprecated Use @ref SiVoice_setControlInterfaceGetTime
*/
int ProSLIC_setControlInterfaceGetTime (controlInterfaceType *pCtrlIntf, system_getTime_fptr getTime_fptr);
/** @} PROSLIC_TIMER */
/*****************************************************************************/
/** @defgroup PROSLIC_PROC_CONTROL ProSLIC Process control
* @{*/
/**
* @brief
* This function assoicates a user defined semaphore/critical section
* function with the given interface.
*
* @param[in,out] pCtrlIntf - the interface to associate the function with.
* @param[in] semaphore_fptr - the function pointer for semaphore control.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
* @deprecated Use @ref SiVoice_setControlInterfaceSemaphore
*/
int ProSLIC_setControlInterfaceSemaphore (controlInterfaceType *pCtrlIntf, ctrl_Semaphore_fptr semaphore_fptr);
/** @} PROSLIC_PROC_CONTROL */
/** @} PROSLIC_IF_CFG */
/*****************************************************************************/
/** @defgroup GEN_CFG General configuration
* @{
*/
/**
* @brief
* This function initializes the various channel structure elements.
* This function does not access the chipset directly, so SPI/GCI
* does not need to be up during this function call.
*
* It is suggested to migrate to the @ref SiVoice_SWInitChan in new
* implementations.
*
* @param[in,out] hProslic - which channel to initialize.
* @param[in] channel - Which channel index is this. For example, for a 4 channel system, this would typically range from 0 to 3.
* @param[in] chipType - chipset family type for example @ref SI321X_TYPE or @ref SI3217X_TYPE
* @param[in] deviceObj - Device structure pointer associated with this channel
* @param[in] pCtrlIntf - Control interface associated with this channel
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
* @deprecated Use @ref SiVoice_SWInitChan
*/
int ProSLIC_SWInitChan (proslicChanType_ptr hProslic,int channel,int chipType, ProslicDeviceType*deviceObj,controlInterfaceType *pCtrlIntf);
/**
*
* @brief
* Calibrates the ProSLIC (on some variants). This typically only needs to be performed during
* initial setup and will itterate through all channels specified by the size parameter starting
* from 0.
*
* @param[in] hProslic - array of channels
* @param[in] size - number of channels present/number to itterate through.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
* @sa PROSLIC_LB_CALIBRATION
* @deprecated This function does not need to be called externally since the normal initialization function will take care of this.
*/
int ProSLIC_Cal (proslicChanType_ptr *hProslic, int size);
/**
* @brief
* This function calls the user supplied reset function to put and take out the channel from reset. This is
* typically done during initialization and may be assumed to be a "global" reset - that is 1 reset per
* daisychain vs. 1 per device.
*
* @note This function can take more than 500 mSec to complete.
*
* @param[in] hProslic - which channel to reset, if a "global reset", then any channel on the daisy chain is sufficient.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
*/
int ProSLIC_Reset (proslicChanType_ptr hProslic);
/**
* @brief
* Safely shutdown channel w/o interruptions to other active channels
*
* @param[in] hProslic - which channel to shut down
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*/
int ProSLIC_ShutdownChannel (proslicChanType_ptr hProslic);
/**
* @brief
* Loads patch and initializes all ProSLIC devices. Performs all calibrations except
* longitudinal balance.
*
* @param[in] hProslic - which channel(s) to initialize, if size > 1, then the start of the array
* of channels to be initialized.
* @param[in] size - the number of channels to initialize.
* @param[in] preset - general configuration preset to apply
*
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
* @sa ProSLIC_Init
*/
int ProSLIC_Init_MultiBOM (proslicChanType_ptr *hProslic, int size, int preset);
/**
* @brief
* Loads patch and initializes all ProSLIC devices. Performs all calibrations except
* longitudinal balance.
*
* @param[in] hProslic - which channel(s) to initialize, if size > 1, then the start of the array
* of channels to be initialized.
* @param[in] size - the number of channels to initialize.
*
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
* @sa ProSLIC_InitBroadcast
*/
int ProSLIC_Init (proslicChanType_ptr *hProslic, int size);
/**
* @brief
* Loads patch and initializes all ProSLIC devices on the same daisy chain including
* performing all calibrations and applying the patch (if necessary).
*
* @param[in] hProslic - which channel(s) to initialize
*
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
* @deprecated
* Use the @ref ProSLIC_Init function
*
* @sa ProSLIC_Init
*/
int ProSLIC_InitBroadcast (proslicChanType_ptr *hProslic);
/**
* @brief
* Performs soft reset then calls ProSLIC_Init()
*
* @param[in] hProslic - which channel(s) to initialize, if size > 1, then the start of the array
* of channels to be initialized.
* @param[in] size - the number of channels to initialize.
*
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
* @sa ProSLIC_InitBroadcast
*/
int ProSLIC_Reinit (proslicChanType_ptr hProslic, int size);
/**
* @brief
* Loads registers and RAM in the ProSLICs specicified.
*
* @param[in] pProslic - array of channels
* @param[in] pRamTable - array of RAM locations and values to write
* @param[in] pRegTable - array of register locations and values to write
* @param[in] size - number of ProSLICS to write to.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
* @deprecated This function should NOT be used since it can bypass the standard initialization/operational state of the
* ProSLIC.
*/
int ProSLIC_LoadRegTables (proslicChanType_ptr *pProslic,ProslicRAMInit *pRamTable, ProslicRegInit *pRegTable, int size);
/**
* @brief
* Configure impedence synthesis
*
* @param[in] hProslic - which channel to configure
* @param[in] preset - which impedence configuration to load from the constants file.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
* @note This function can be disabled by @ref DISABLE_ZSYNTH_SETUP
*/
int ProSLIC_ZsynthSetup (proslicChanType_ptr hProslic,int preset);
/**
* @brief
* This function configures the CI bits (GCI mode)
*
* @param[in] hProslic - which channel to configure
* @param[in] preset - which GCI preset to use from the contstants file
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
* @note This function can be disabled by @ref DISABLE_CI_SETUP
*/
int ProSLIC_GciCISetup (proslicChanType_ptr hProslic,int preset);
/**
* @brief
* This function sets the modem tone detection parameters for ProSLIC by loading a modem
* tone detection preset
*
* @param[in] hProslic - which channel to configure
* @param[in] preset - which MODEM preset to use.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
*/
int ProSLIC_ModemDetSetup (proslicChanType_ptr hProslic,int preset);
/*****************************************************************************/
/** @defgroup PROSLIC_ERROR_CONTROL Return code functions
* This group of functions are used for when the ProSLIC API function does
* not reutrn a standard error value and instead returns back some other value.
* You may call these functions to see if there was an error preset and to clear
* the error state.
*
* @{
*/
/**
* @brief
* This function returns the error flag that may be set by some function in where
* @ref errorCodeType is not returned.
*
* @note For functions that DO return errorCodeType, the return value here is undefined.
*
* @param[in] hProslic - which channel to clear the error flag
* @param[in,out] error - The current value of error flag.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
* @deprecated Use @ref SiVoice_getErrorFlag
*
* @sa ProSLIC_clearErrorFlag
*/
int ProSLIC_getErrorFlag (proslicChanType_ptr hProslic, int *error);
/**
* @brief
* This function clears the error flag that may be set by some function in where
* @ref errorCodeType is not returned.
*
* @param[in,out] hProslic - which channel to clear the error flag
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
* @deprecated Use @ref SiVoice_clearErrorFlag
*
* @sa ProSLIC_getErrorFlag
*/
int ProSLIC_clearErrorFlag (proslicChanType_ptr hProslic);
/** @} PROSLIC_ERROR_CONTROL */
/*****************************************************************************/
/** @defgroup PROSLIC_DEBUG Debug
* This group of functions enables/disables debug messages as well as dump
* register contents.
* @{
*/
/**
* @brief
* This function enables or disables the debug mode, assuming @ref ENABLE_DEBUG is set in the configuration file.
*
* @param[in] hProslic - which channel to set the debug flag.
* @param[in] debugEn - 0 = Not set, 1 = set.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
* @deprecated Use @ref SiVoice_setSWDebugMode
*
*/
int ProSLIC_setSWDebugMode (proslicChanType_ptr hProslic, int debugEn);
/**
* @brief
* This function allows access to SPI read register function pointer from interface
*
* @param[in] hProslic - pointer to channel structure
* @param[in] addr - address to read
* @retval uInt8 - register contents
*
*/
uInt8 ProSLIC_ReadReg (proslicChanType_ptr hProslic, uInt8 addr);
/**
* @brief
* This function allows access to SPI write register function pointer from interface
*
* @param[in] hProslic - pointer to channel structure
* @param[in] addr - address to write
* @param[in] data to be written
* @retval int - @ref RC_NONE
*
*/
int ProSLIC_WriteReg (proslicChanType *pProslic, uInt8 addr, uInt8 data);
/**
* @brief
* This function allows access to SPI read RAM function pointer from interface
*
* @param[in] hProslic - pointer to channel structure
* @param[in] addr - address to read
* @retval ramData - RAM contents
*
*/
ramData ProSLIC_ReadRAM (proslicChanType *pProslic, uInt16 addr);
/**
* @brief
* This function allows access to SPI write RAM function pointer from interface
*
* @param[in] hProslic - pointer to channel structure
* @param[in] addr - address to write
* @param[in] data to be written
* @retval int - @ref RC_NONE
*
*/
int ProSLIC_WriteRAM (proslicChanType *pProslic, uInt16 addr, ramData data);
/**
* @brief
* This function dumps to console the register contents of several
* registers and RAM locations.
*
* @param[in] pProslic - which channel to dump the register contents of.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
*/
int ProSLIC_PrintDebugData (proslicChanType *pProslic);
/**
* @brief
* This function dumps the registers to the console using whatever
* I/O method is defined by LOGPRINT
*
* @param[in] pProslic - which channel to dump the register contents of.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
*/
int ProSLIC_PrintDebugReg (proslicChanType *pProslic);
/**
* @brief
* This function dumps the RAM to the console using whatever
* I/O method is defined by LOGPRINT
*
* @param[in] pProslic - which channel to dump the RAM contents of.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
*/
int ProSLIC_PrintDebugRAM (proslicChanType *pProslic);
/** @} PROSLIC_DEBUG */
/*****************************************************************************/
/** @defgroup PROSLIC_ENABLE Enable/disable channels (for init)
* @{
*/
/**
* @brief
* This function sets the channel enable status. If NOT set, then when
* the various initialization routines such as @ref ProSLIC_SWInitChan is called,
* then this particular channel will NOT be initialized.
*
* This function does not access the chipset directly, so SPI/GCI
* does not need to be up during this function call.
*
* @param[in,out] hProslic - which channel to return the status.
* @param[in] chanEn - The new value of the channel enable field. 0 = NOT enabled, 1 = enabled.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
* @sa ProSLIC_getChannelEnable
*/
int ProSLIC_setChannelEnable (proslicChanType_ptr hProslic, int chanEn);
/**
* @brief
* This function returns back if the channel is enabled or not.
* This function does not access the chipset directly, so SPI/GCI
* does not need to be up during this function call.
*
* @param[in] hProslic - which channel to return the status.
* @param[in,out] chanEn - The current value of if the channel is enabled. 0 = NOT enabled, 1 = enabled.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
* @sa ProSLIC_setChannelEnable
*/
int ProSLIC_getChannelEnable (proslicChanType_ptr hProslic, int* chanEn);
/**
* @brief
* This function sets the channel enable status of the FXO channel on ProSLIC devices
* with integrated FXO. If NOT set, then when
* the various initialization routines such as @ref ProSLIC_SWInitChan is called,
* then this particular channel will NOT be initialized.
*
* This function does not access the chipset directly, so SPI/GCI
* does not need to be up during this function call.
*
* @param[in,out] pProslic - which channel to return the status.
* @param[in] enable - The new value of the channel enable field. 0 = NOT enabled, 1 = enabled.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
* @sa ProSLIC_getChannelEnable
*/
int ProSLIC_SetDAAEnable(proslicChanType *pProslic, int enable);
/** @} PROSLIC_ENABLE */
/*****************************************************************************/
/** @defgroup PROSLIC_PATCH Patch management.
* This group of functions write and verify the patch data needed by the
* ProSLIC chipset.
* @{
*/
/**
* @brief
* Calls patch loading function for a particular channel/ProSLIC
*
* @param[in] hProslic - which channel/ProSLIC should be patched
* @param[in] pPatch - the patch data
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
* @note This function should not be called directly under normal circumstances since the initialization function should
* perform this operation.
*
* @sa ProSLIC_Init
*/
int ProSLIC_LoadPatch (proslicChanType_ptr hProslic,proslicPatch *pPatch);
/**
* @brief
* Verifies patch loading function for a particular channel/ProSLIC
*
* @param[in] hProslic - which channel/ProSLIC should be patched
* @param[in] pPatch - the patch data to verify was written to.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
* @note This function should not be called directly under normal circumstances since the initialization function should
* perform this operation, unless @ref DISABLE_VERIFY_PATCH is defined.
*
* @sa ProSLIC_Init
*/
int ProSLIC_VerifyPatch (proslicChanType_ptr hProslic,proslicPatch *pPatch);
/** @} PROSLIC_PATCH */
/*****************************************************************************/
/** @defgroup PROSLIC_GPIO GPIO Control
* This group of functions configure, read and write the GPIO status pins.
* @{
*/
/**
* @brief
* This function configures the ProSLIC GPIOs by loading a gpio preset that was
* set in the configuration tool.
* @param[in] hProslic - which channel to configure the GPIO pins.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
* @sa ProSLIC_GPIOControl
*/
int ProSLIC_GPIOSetup (proslicChanType_ptr hProslic);
/**
* @brief
* This function controls the GPIOs of the ProSLIC.
*
* @param[in] hProslic - which channel to modify
* @param[in,out] pGpioData - pointer to GPIO status (typcially 1 byte)
* @param[in] read - 1 = Read the status, 0 = write the status
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
* @sa ProSLIC_GPIOSetup
*/
int ProSLIC_GPIOControl (proslicChanType_ptr hProslic,uInt8 *pGpioData, uInt8 read);
/** @} PROSLIC_GPIO */
/** @} GEN_CFG */
/*****************************************************************************/
/** @defgroup PROSLIC_PULSE_METER Pulse Metering
*
* This group contains functions related to pulse metering.
* @{
*/
/**
* @brief
* This function configures the ProSLIC pulse metering by loading a pulse metering preset.
*
* @param[in] hProslic - which channel should be configured
* @param[in] preset - which preset to load from the defined settings made in the configuration tool.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
* @sa ProSLIC_PulseMeterStart ProSLIC_PulseMeterStop
*/
int ProSLIC_PulseMeterSetup (proslicChanType_ptr hProslic,int preset);
/**
* @brief
* This function starts the pulse metering tone.
*
* @param[in] hProslic - which channel should play the tone.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
* @sa ProSLIC_PulseMeterSetup ProSLIC_PulseMeterStop
*
*/
int ProSLIC_PulseMeterStart (proslicChanType_ptr hProslic);
/**
* @brief
* This function stops the pulse metering tone.
*
* @param[in] hProslic - which channel should play the tone.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
* @sa PProSLIC_PulseMeterStart ProSLIC_PulseMeterSetup
*
*/
int ProSLIC_PulseMeterStop (proslicChanType_ptr hProslic);
/** @} PROSLIC_PULSE_METER */
/*****************************************************************************/
/** @defgroup PROSLIC_INTERRUPTS Interrupt control and decode
* @{
*/
/**
* @brief
* Enables interrupts configured in the general configuration data structure.
*
* @param[in] hProslic - which channel to enable the interrupts.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
*/
int ProSLIC_EnableInterrupts (proslicChanType_ptr hProslic);
/**
* @brief
* This function reads the interrupts from the ProSLIC and places them into
* a @ref proslicIntType structure which contains up to @ref MAX_PROSLIC_IRQS
* interrupts.
*
* @param[in] hProslic - which channel to enable the interrupts.
* @param[in,out] pIntData - this structure contains the interupts pending and the number of interrupts.
* @retval int - number of interrupts pending or RC_CHANNEL_TYPE_ERR if wrong chip type or 0 for no interrupts.
*
*/
int ProSLIC_GetInterrupts (proslicChanType_ptr hProslic,proslicIntType *pIntData);
/**
* @brief
* This function disables and clears interrupts on the given channel.
*
* @param[in] hProslic - which channel to disable
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*/
int ProSLIC_DisableInterrupts (proslicChanType_ptr hProslic);
/** @} PROSLIC_INTERRUPTS */
/*****************************************************************************/
/** @defgroup SIGNALING Signaling - ring & line state, and hook state
* @{
*/
/**
* Function: PROSLIC_ReadHookStatus
*
* @brief
* Determine hook status
* @param[in] hProslic - which channel to read from.
* @param[out] *pHookStat - will contain either @ref PROSLIC_ONHOOK or @ref PROSLIC_OFFHOOK
*
*/
int ProSLIC_ReadHookStatus (proslicChanType_ptr hProslic,uInt8 *pHookStat);
/*****************************************************************************/
/** @defgroup LINESTATUS Line Feed status
* @{
*/
/**
* @brief
* This function sets the linefeed state.
*
* @param[in] hProslic - which channel to modify
* @param[in] newLinefeed - new line feed state - examples: LF_OPEN, LF_FWD_ACTIVE
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*/
int ProSLIC_SetLinefeedStatus (proslicChanType_ptr hProslic,uInt8 newLinefeed);
/**
* @brief
* This function sets the linefeed state for all channels on the same daisychain.
*
* @param[in] hProslic - which channel to modify
* @param[in] newLinefeed - new line feed state - examples: LF_OPEN, LF_FWD_ACTIVE
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*/
int ProSLIC_SetLinefeedStatusBroadcast (proslicChanType_ptr hProslic,uInt8 newLinefeed);
/**
* @brief
* This function sets the polarity/wink state of the channel.
*
* @param[in] hProslic - which channel to modify
* @param[in] abrupt - to change the state immeediately
* @param[in] newPolRevState - new polarity state - examples: POLREV_STOP, POLREV_START and WINK_START
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*/
int ProSLIC_PolRev (proslicChanType_ptr hProslic,uInt8 abrupt,uInt8 newPolRevState);
/** @} LINESTATUS */
/*****************************************************************************/
/** @defgroup RING_CONTROL Ring generation
* @{
*/
/**
* @brief
* Configure the ringer to the given preset (see your constants header file for exact value to use).
* This includes timing, cadence, OHT mode, voltage levels, etc.
*
* @param[in] hProslic - which channel to configure
* @param[in] preset - which of the xxxx_Ring_Cfg structures to use to configure the channel.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
* @note This function can be compiled out by defining @ref DISABLE_RING_SETUP
*
* @sa ProSLIC_dbgSetRinging ProSLIC_RingStart ProSLIC_RingStop
*/
int ProSLIC_RingSetup (proslicChanType_ptr hProslic,int preset);
/**
* @brief
* Starts the ringer as confgured by @ref ProSLIC_RingSetup . If the active and inactive timers are enabled,
* the ProSLIC will automatically turn on/off the ringer as programmed, else one will need to
* manually implement the ring cadence. In either case, one will need to call ProSLIC_RingStop to
* stop the ringer or one may call @ref ProSLIC_SetLinefeedStatus to change the state directly.
*
* @param[in] hProslic - which channel to enable ringing.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
* @note This function can be compiled out by defining @ref DISABLE_RING_SETUP
*
* @sa ProSLIC_dbgSetRinging ProSLIC_RingStop ProSLIC_RingSetup
*/
int ProSLIC_RingStart (proslicChanType_ptr hProslic);
/**
* @brief
* Stop the ringer on the given channel and set the line state to forward active.
*
* @param[in] hProslic - which channel to modify.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
* @sa ProSLIC_RingSetup ProSLIC_RingStart
*/
int ProSLIC_RingStop (proslicChanType_ptr hProslic);
/**
* @brief
* Provisionary function for setting up Ring type, frequency, amplitude and dc offset and
* to store them in the given preset.
*
* @note: This function calculates the values, it does not set them.
*
* @param[in] pProslic - which channel to modify
* @param[in] ringCfg - how to configure the channel's ringer
* @param[in] preset - where to store the new configuration.
* @sa ProSLIC_RingSetup ProSLIC_RingStart ProSLIC_RingStop
*/
int ProSLIC_dbgSetRinging (proslicChanType *pProslic, ProSLIC_dbgRingCfg *ringCfg, int preset);
/** @} RING_CONTROL */
/** @} SIGNALING */
/*****************************************************************************/
/** @defgroup PROSLIC_AUDIO Audio
* This group of functions contains routines to configure the PCM bus, to generate tones, and to send FSK data.
*
* In order to start using the PCM bus, you would typically initialize the PCM bus with code similar to
* the following:
*
* @code
* if( (ProSLIC_PCMSetup(myProSLIC, MY_COMPANDING) != RC_NONE)
* || (ProSLIC_PCMTimeSlotSetup(myProSLIC, pcm_ts, pcm_ts) != RC_NONE)
* || (ProSLIC_PCMStart(myProSLIC) != RC_NONE))
* {
* return MY_PCM_INIT_ERROR;
* }
* @endcode
*
* @{
* @defgroup TONE_GEN Tone generation
* This group of functions is related to playing out general tones - such as dial tone, busy tone, etc. One would
* typically call @ref ProSLIC_ToneGenSetup first followed by @ref ProSLIC_ToneGenStart and after some time, a call to
* @ref ProSLIC_ToneGenStop to stop the tone. The direction of the tone and cadence (if any) are configured using the
* GUI configuration tool's TONE dialog box and then saved in the constants file.
*
* @{
*/
/**
* @brief
* Configure the tone generator to the given preset (see your constants header file for exact value to use). It does NOT
* play a particular tone out.
*
* @warning If @ref ProSLIC_FSKSetup was called earlier, this function will need to be called again.
*
* @param[in] hProslic - which channel to configure
* @param[in] preset - which of the xxxx_Tone_Cfg structures to use to configure the channel.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
* @note This function can be compiled out by defining @ref DISABLE_TONE_SETUP.
*
* @note Typically, if one is using the ProSLIC for tone generation, you will be calling this function prior to each call
* into @ref ProSLIC_ToneGenStart so that the correct tone is played out.
*/
int ProSLIC_ToneGenSetup (proslicChanType_ptr hProslic,int preset);
/**
* @brief
* This function starts the tone configured by @ref ProSLIC_ToneGenSetup.
* It is assumed that the @ref PROSLIC_AUDIO setup was performed
* prior to calling this function. Also, it is suggested that
* @ref ProSLIC_ToneGenSetup be called if @ref FSK_CONTROL
* functions were used.
*
* @param[in] hProslic - which channel should play the tone.
* @param[in] timerEn - are the timers to be enabled? 1 = Yes, 0 = No. When in doubt, set to 1.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
* @sa ProSLIC_ToneGenSetup ProSLIC_ToneGenStop
*/
int ProSLIC_ToneGenStart (proslicChanType_ptr hProslic, uInt8 timerEn);
/**
* @brief
* This function turns off tone generation initiated by @ref ProSLIC_ToneGenStart.
*
* @param[in] hProslic - which channel should stop playing the tone.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
* @sa ProSLIC_ToneGenStart ProSLIC_ToneGenSetup
*/
int ProSLIC_ToneGenStop (proslicChanType_ptr hProslic);
/** @} TONE_GEN */
/*****************************************************************************/
/** @defgroup FSK_CONTROL FSK/Caller ID generation
* This group of functions is related to FSK generation, typically used with Caller ID/Call Waiting
* functionality. To set the frequencies, the data rate, and the FSK FIFO depth, please use the configuration
* GUI FSK dialog box.
*
* Here's a simple example code fragment to send data via FSK:
*
* @code
* if( ProSLIC_FSKSetup(myProSLICChan, PROSLIC_NORTH_AMERICA_FSK) == RC_NONE)
* {
* ProSLIC_EnableCID(myProSLICChan);
*
* bytes_left_to_send = bufsz;
*
* do
* {
* if(bytes_left_to_send < FIFO_DEPTH)
* {
* bytes_to_send = bytes_left_to_send;
* }
* else
* {
* bytes_to_send = FIFO_DEPTH;
* }
*
* if( ProSLIC_SendCID(myProSLICChan,buf,bytes_to_send) != RC_NONE)
* {
* ProSLIC_DisableCID(myProSLICChan);
* return MY_FSK_ERROR;
* }
*
* bytes_left_to_send -= bytes_to_send;
*
* if(bytes_left_to_send)
* {
* do
* {
* ProSLIC_CheckCIDBuffer(myProSLICChan, &is_fifo_empty);
*
* } while( is_fifo_empty != 1 );
* }
*
* }while( bytes_left_to_send > 0);
*
* ProSLIC_DisableCID(myProSLICChan);
* @endcode
*
* @note The above code fragment is sub-optimal since it does constantly poll the CID buffer
* state - one may want to implement the actual code using interrupts.
* @{
*/
/**
* @brief
* Configures the FSK generator from a configuration generated by the config tool.
*
* @warning If @ref ProSLIC_ToneGenSetup was called earlier, this function will need to be called again.
*
* @param[in] hProslic - which channel to configure
* @param[in] preset - which FSK configuration to use.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
* @note This function can be compiled out by defining DISABLE_FSK_SETUP
*/
int ProSLIC_FSKSetup (proslicChanType_ptr hProslic,int preset);
/**
* @brief
* This function enables FSK mode and clears the FSK FIFO. It is assumed that PCM has been enabled and that @ref ProSLIC_FSKSetup
* has been called at some point.
*
* @warning If @ref ProSLIC_ToneGenSetup was called earlier, @ref ProSLIC_FSKSetup will need to be called again.
*
* @param[in] hProslic - which channel to check upon.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
*/
int ProSLIC_EnableCID (proslicChanType_ptr hProslic);
/**
* @brief
* This function disables FSK mode.
*
* @param[in] hProslic - which channel to disable FSK mode.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
*/
int ProSLIC_DisableCID (proslicChanType_ptr hProslic);
/**
* @brief
* Check if the FSK FIFO is empty or not.
*
* @param[in] hProslic - which channel to check upon.
* @param[out] fsk_buf_avail - is the buffer available? 1 = Yes, 0 = No.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
* @note - This modifies the IRQ1 register contents, so some other interrupts may be lossed. An alternative is to enable the
* FSK FIFO interrupt and trigger off of it when it does occur in your interrupt service routine.
*/
int ProSLIC_CheckCIDBuffer (proslicChanType_ptr hProslic, uInt8 *fsk_buf_avail);
/**
* @brief
* Send numBytes as FSK encoded data. It is assumed that numBytes <= FIFO Depth (typically 8) and that the FIFO
* is free. It is also assumed that @ref ProSLIC_PCMStart has been called and that we're in
* @ref LF_FWD_OHT or @ref LF_REV_OHT mode for Type-1 or @ref LF_REV_ACTIVE or @ref LF_FWD_ACTIVE
* if we're in Type-2 caller ID.
*
* @param[in] hProslic - which channel to send the data through.
* @param[in] buffer - byte array of data to send.
* @param[in] numBytes - number of bytes to send. MUST be less than or equal to the FIFO size
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
* @sa ProSLIC_CheckCIDBuffer ProSLIC_FSKSetup ProSLIC_EnableCID ProSLIC_DisableCID
*/
int ProSLIC_SendCID (proslicChanType_ptr hProslic, uInt8 *buffer, uInt8 numBytes);
/**
* @brief Control if the start/stop bits are enabled.
*
* @param[in] hProslic - which channel to adjust
* @param[in] enable_startStop - TRUE - start/stop bits are enabled, FALSE - disabled
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
* @note: This does not replace @ref ProSLIC_FSKSetup, but is a suppliment that toggles
* one of the registers that the preset modifies. It is assumed that @ref ProSLIC_FSKSetup
* was called at some point earlier in the code flow.
*/
int ProSLIC_ModifyCIDStartBits(proslicChanType_ptr hProslic, uInt8 enable_startStop);
/** @} FSK_CONTROL */
/*****************************************************************************/
/** @defgroup AUDIO_CONTROL Audio control/configuration
* @{
*/
/** @defgroup PCM_CONTROL PCM control
* This group of functions is used to configure and control the PCM bus. It is essential that @ref ProSLIC_PCMSetup,
* @ref ProSLIC_PCMTimeSlotSetup and @ref ProSLIC_PCMStart are called prior to any tone or FSK generation.
*
* See @ref PROSLIC_AUDIO code fragment on how the functions relate during initialization.
*
* @{
*/
/**
* @brief
* This configures the PCM bus with parameters such as companding and data latching timing.
*
* @param[in] hProslic - which channel should be configured
* @param[in] preset - which preset to use from the constants file (see configuration tool, PCM dialog box)
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
* @sa ProSLIC_PCMTimeSlotSetup ProSLIC_PCMStart
*/
int ProSLIC_PCMSetup (proslicChanType_ptr hProslic,int preset);
/**
* @brief
* This configures the ProSLIC to latch and send the PCM data at a particular timeslot in terms of PCM clocks (PCLK).
*
* Typically, for aLaw and uLaw, one can use the following calculation to set the rxcount and txcount parameters:
*
* rxcount = txcount = (channel_number)*8;
*
* For 16 bit linear, one can do the following:
*
* rxcount = txcount = (channel_number)*16;
*
* where channel_number = which ProSLIC channel on the PCM bus. For example, if one were to have 2 dual channel
* ProSLIC's on the same PCM bus, this value would range from 0 to 3.
*
* @param[in] hProslic - which channel should be configured
* @param[in] rxcount - how many clocks until reading data from the PCM bus
* @param[in] txcount - how many clocks until writing data to the PCM bus.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
* @sa ProSLIC_PCMSetup ProSLIC_PCMStart
*/
int ProSLIC_PCMTimeSlotSetup (proslicChanType_ptr hProslic, uInt16 rxcount, uInt16 txcount);
/**
* @brief
* This enables PCM transfer on the given ProSLIC channel.
*
* @param[in] hProslic - - which channel should be enabled
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
* @sa ProSLIC_PCMSetup ProSLIC_PCMTimeSlotSetup ProSLIC_PCMStop
*/
int ProSLIC_PCMStart (proslicChanType_ptr hProslic);
/**
* @brief
* This disables PCM transfer on the given ProSLIC channel. Typically, this is called for debugging
* purposes only.
*
* @param[in] hProslic - - which channel should be disabled
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
* @sa ProSLIC_PCMSetup ProSLIC_PCMTimeSlotSetup ProSLIC_PCMStart
*/
int ProSLIC_PCMStop (proslicChanType_ptr hProslic);
/**
* @brief
* Program desired loopback test mode for the given channel.
*
* @param[in] hProslic - which channel should be modified
* @param[in] newMode - what is the desired loopback mode.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
*/
int ProSLIC_SetLoopbackMode (proslicChanType_ptr hProslic, ProslicLoopbackModes newMode);
/**
* @brief
* Program desired mute test mode for the given channel.
*
* @param[in] hProslic - which channel should be modified
* @param[in] muteEn - what is the desired mode.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
*/
int ProSLIC_SetMuteStatus (proslicChanType_ptr hProslic, ProslicMuteModes muteEn);
/** @} PCM_CONTROL */
/*****************************************************************************/
/** @defgroup GAIN_CONTROL Gain control
* @{
*/
/**
* @brief
* Sets the TX audio gain (toward the network). This funcion DOES NOT actually calculate the values for the preset.
* To dynamically calculate the values, you would need to call @ref ProSLIC_dbgSetTXGain .
*
* @param[in] hProslic - which channel to configure
* @param[in] preset - which preset to use (this may be from the constants file)
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
* @note One can use this in conjunction with @ref ProSLIC_dbgSetTXGain to dynamically
* change the audio gain. It is important to have the presets of both routines match.
*
* The following code * fragment will set the TX audio gain to -5 dB:
*
* @code
* ProSLIC_dbgSetTXGain(myChannel, -5, MY_IMPEDENCE,0);
* ProSLIC_TXAudioGainSetup(myChannel,0);
* @endcode
*
* @sa ProSLIC_RXAudioGainSetup ProSLIC_dbgSetTXGain ProSLIC_AudioGainSetup
*/
int ProSLIC_TXAudioGainSetup (proslicChanType_ptr hProslic,int preset);
/**
* @brief
* Configures the RX audio gain (toward the telephone). This funcion DOES NOT actually calculate the values for the preset.
* To dynamically calculate the values, you would need to call @ref ProSLIC_dbgSetRXGain .
*
* @param[in] hProslic - which channel to configure
* @param[in] preset - which preset to use (this may be from the constants file)
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
* @note One can use this in conjunction with @ref ProSLIC_dbgSetRXGain to dynamically
* change the audio gain. It is important to have the presets of both routines match.
*
* The following code * fragment will set the RX audio gain to -1 dB:
*
* @code
* ProSLIC_dbgSetRXGain(myChannel, -1, MY_IMPEDENCE,0);
* ProSLIC_RXAudioGainSetup(myChannel,0);
* @endcode
*
* @sa ProSLIC_TXAudioGainSetup ProSLIC_dbgSetRXGain ProSLIC_AudioGainSetup
*/
int ProSLIC_RXAudioGainSetup (proslicChanType_ptr hProslic,int preset);
/**
* @brief
* Configures and sets the audio gains - for both RX (toward the phone) and the TX (toward the network). Unlike
* the @ref ProSLIC_RXAudioGainSetup and @ref ProSLIC_TXAudioGainSetup this does both the calculations and then
* configures the given channel in one step. It is assumed that the preset gain array is at least 2 elements in size.
*
* @param[in] hProslic - which channel to configure
* @param[in] rxgain - what is the gain/loss of the RX transmit path in 1 dB units (negative = attenuation)
* @param[in] txgain - what is the gain/loss of the TX transmit path in 1 dB units (negative = attenuation)
* @param[in] preset - what is the impedance preset value
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
* The following code * fragment will set the RX audio gain to -1 dB snd TX audio gain to -5 dB:
*
* @code
* ProSLIC_AudioGain(myChannel, -1, -5, MY_IMPEDENCE);
* @endcode
*
* @sa ProSLIC_TXAudioGainSetup ProSLIC_dbgSetRXGain ProSLIC_dbgSetRXGain ProSLIC_dbgSetTXGain
*/
int ProSLIC_AudioGainSetup (proslicChanType_ptr hProslic,int32 rxgain,int32 txgain,int preset);
/**
* @brief
* This function calculates the preset values for the RX audio (toward the telephone) - it does NOT set the
* actual register values. For that, please use @ref ProSLIC_RXAudioGainSetup .
*
* @param[in] pProslic - which channel to configure
* @param[in] gain - gain to set the preset values to.
* @param[in] impedance_preset - impedence preset in the constants file.
* @param[in] audio_gain_preset - index to the audio gain preset to store the value.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
* @sa ProSLIC_RXAudioGainSetup ProSLIC_AudioGainSetup ProSLIC_dbgSetTXGain
*/
int ProSLIC_dbgSetRXGain (proslicChanType *pProslic, int32 gain, int impedance_preset, int audio_gain_preset);
/**
* @brief
* This function calculates the preset values for the TX audio (toward the network) - it does NOT set the
* actual register values. For that, please use @ref ProSLIC_TXAudioGainSetup .
*
* @param[in] pProslic - which channel to configure
* @param[in] gain - gain to set the preset values to.
* @param[in] impedance_preset - impedence preset in the constants file.
* @param[in] audio_gain_preset - index to the audio gain preset to store the value.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
* @sa ProSLIC_TXAudioGainSetup ProSLIC_AudioGainSetup ProSLIC_dbgSetRXGain
*/
int ProSLIC_dbgSetTXGain (proslicChanType *pProslic, int32 gain, int impedance_preset, int audio_gain_preset);
/** @} GAIN_CONTROL */
/** @} AUDIO_CONTROL */
/** @} PROSLIC_AUDIO */
/*****************************************************************************/
/** @defgroup PD_DETECT Pulse dial detection
*
* This function group has routines used to implement a pulse dial detection
* mechanism. The outline of how to use these functions is as follows:
*
* - Initialize the data structure w/ @ref ProSLIC_InitializeDialPulseDetect
* - When hook change is detected, call @ref ProSLIC_DialPulseDetect
* - After calling @ref ProSLIC_DialPulseDetect and we're onhook, call
* @ref ProSLIC_DialPulseDetectTimeout to see if we need to re-initialize
* the state machine.
*
* @note This set of functions require that the elapsed timer functions
* documented in @ref PROSLIC_CUSTOMER_TIMER are implemented.
*
* @{
*/
/**
* @brief
* Initialize pulse dial detection parameters.
*
* @param[in,out] pPulse - the structure that is to be initialized.
* @param[in] offHookTime - a timer object suitable to be passed to a function of type @ref system_timeElapsed_fptr
* @param[in] onHookTime - a timer object suitable to be passed to a function of type @ref system_timeElapsed_fptr
*
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*/
int ProSLIC_InitializeDialPulseDetect(pulseDialType *pPulse,void *offHookTime,void *onHookTime);
/**
* @brief
* Implements pulse dial detection and should be called at every hook transistion.
*
* @param[in] pProslic - which channel had a hook transition.
* @param[in] pPulsedialCfg - what is the criteria to determine on/off hook states.
* @param[in,out] pPulseDialData - contians the timer information that was set in
* @ref ProSLIC_InitializeDialPulseDetect as well as the pulse digit detected
*
* @retval int - 0 = no pulse digit detected, 1 = we detected a pulse digit that met the timing criteria and that in @ref pulseDialType contains the digit detected.
*/
int ProSLIC_DialPulseDetect (proslicChanType *pProslic, pulseDial_Cfg *pPulsedialCfg, pulseDialType *pPulseDialData);
/**
* @brief
* This function implements pulse dial detection and should be called when a
* pulse dial timeout (e.g. max offhook or onhook time exceeded) is suspected.
*
* @param[in] pProslic - which channel had a hook transition.
* @param[in] pPulsedialCfg - what is the criteria to determine on/off hook states.
* @param[in,out] pPulseDialData - contians the timer information that was set in
* @ref ProSLIC_InitializeDialPulseDetect as well as the pulse digit detected
* @retval @ref ON_HOOK_TIMEOUT - did not detect a digit, 0 = no digit detected, else the digit detected.
*/
int ProSLIC_DialPulseDetectTimeout (proslicChanType *pProslic, pulseDial_Cfg *pPulsedialCfg, pulseDialType *pPulseDialData);
/** @} PD_DETECT */
/*****************************************************************************/
/** @addtogroup PROSLIC_AUDIO
* @{
* @defgroup PROSLIC_DTMF_DECODE DTMF Decode
* This section covers DTMF decoding.
*
* @note Not all chipsets support this capability. Please review your chipset
* documentation to confirm this capability is supported.
* @{
*/
/**
* @brief
* Configure the DTMF Decoder - assumes PCM setup procedure has been done.
*
* @warning Not all ProSLIC chipsets have a DTMF decoder. Please review your chipset to make
* sure this capability exists.
*
* @param[in] hProslic - which channel to configure
* @param[in] preset - which DTMF preset to use.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
* @note This function can be compiled out with @ref DISABLE_DTMF_SETUP being defined.
*/
int ProSLIC_DTMFDecodeSetup (proslicChanType_ptr hProslic,int preset);
/**
* @brief
* Read/Decode DTMF digits. The "raw" hexcode is returned in this function and would require
* further processing. For example, on the Si3217x chipset, the following mapping exists:
*
* 1-9 = no remapping required
* 0 = 0xA
* * = 0xB
* # = 0xC
* A-C = 0xD-0xF
* D = 0
*
* @note This function is only valid after @ref IRQ_DTMF occurred and should be called shortly
* thereafter.
*
* @warning Not all ProSLIC chipsets have a DTMF decoder. Please review your chipset to make
* sure this capability exists.
*
* @param[in] hProslic - which channel is to be decoded.
* @param[out] pDigit - "raw" DTMF value (see comments in description)
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
*
* @sa ProSLIC_DTMFDecodeSetup
*/
int ProSLIC_DTMFReadDigit (proslicChanType_ptr hProslic,uInt8 *pDigit);
/** @} PROSLIC_DTMF_DECODE */
/** @} PROSLIC_AUDIO */
/*****************************************************************************/
/** @defgroup PROSLIC_POWER_CONVERTER Power Converter control
* @{
*/
/**
* @brief
* Powers all DC/DC converters sequentially with delay to minimize peak power draw on VDC.
* @param[in] hProslic - which channel to change state.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
* @sa ProSLIC_PowerDownConverter
*
*/
int ProSLIC_PowerUpConverter(proslicChanType_ptr hProslic);
/**
* @brief
* Safely powerdown dcdc converter after ensuring linefeed
* is in the open state. Test powerdown by setting error
* flag if detected voltage does no fall below 5v.
*
* @param[in] hProslic - which channel to change state.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
* @sa ProSLIC_PowerUpConverter
*
*/
int ProSLIC_PowerDownConverter(proslicChanType_ptr hProslic);
/** @} PROSLIC_POWER_CONVERTER */
/*****************************************************************************/
/** @defgroup PROSLIC_LB_CALIBRATION LB Calibration
* @{
*/
/**
* @brief
* Run canned longitudinal balance calibration.
*
* @param[in] pProslic - start channel to start from for calibration.
* @param[in] size - number of channels to calibrate
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
* @deprecated
* Use the @ref ProSLIC_Init function to perform all calibrations except Longitudinal Balance (LB).
* Use the @ref ProSLIC_LBCal function to perform LB calibration.
*
* @sa ProSLIC_GetLBCalResult ProSLIC_LoadPreviousLBCal ProSLIC_LoadPreviousLBCalPacked ProSLIC_LBCal ProSLIC_GetLBCalResultPacked
*/
int ProSLIC_LBCal (proslicChanType_ptr *pProslic, int size);
/**
* @brief
* This function returns the coefficient results of the last LB calibration.
*
* @param[in] pProslic - which channel to retrieve the values from.
* @param[out] result1 - results read from the last calibration
* @param[out] result2 - results read from the last calibration
* @param[out] result3 - results read from the last calibration
* @param[out] result4 - results read from the last calibration
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
* @sa ProSLIC_LBCal ProSLIC_LoadPreviousLBCal ProSLIC_LoadPreviousLBCalPacked ProSLIC_LBCal ProSLIC_GetLBCalResultPacked
*/
int ProSLIC_GetLBCalResult (proslicChanType *pProslic,int32 *result1,int32 *result2,int32 *result3,int32 *result4);
/**
* @brief
* This function loads previously stored LB calibration results to the appropriate ProSLIC
* RAM locations.
*
* @param[in] pProslic - which channel to program the values
* @param[in] result1 - values to be written
* @param[in] result2 - values to be written
* @param[in] result3 - values to be written
* @param[in] result4 - values to be written
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
* @sa ProSLIC_LBCal ProSLIC_LoadPreviousLBCalPacked ProSLIC_LBCal ProSLIC_GetLBCalResult ProSLIC_GetLBCalResultPacked
*/
int ProSLIC_LoadPreviousLBCal (proslicChanType *pProslic,int32 result1,int32 result2,int32 result3,int32 result4);
/**
* @brief
* This function returns the results of the last LB calibration packed into single int32.
*
* @param[in] pProslic - which channel to retrieve the values from.
* @param[out] result - results - where to store the value
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
* @sa ProSLIC_LBCal ProSLIC_LoadPreviousLBCal ProSLIC_LoadPreviousLBCalPacked ProSLIC_LBCal
*/
int ProSLIC_GetLBCalResultPacked (proslicChanType *pProslic,int32 *result);
/**
* @brief
* This function loads previously stored LB calibration results that are in the packed format.
*
* @param[in] pProslic - which channel to retrieve the values from.
* @param[in] result - results read from @ref ProSLIC_GetLBCalResultPacked
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
* @sa ProSLIC_LBCal ProSLIC_LoadPreviousLBCal ProSLIC_LBCal ProSLIC_GetLBCalResultPacked
*
*/
int ProSLIC_LoadPreviousLBCalPacked (proslicChanType *pProslic,int32 *result);
/** @} PROSLIC_LB_CALIBRATION */
/*****************************************************************************/
/** @addtogroup DIAGNOSTICS
* @{
*/
/**
* @brief
* This function can be used to verify that the SPI interface is functioning
* properly by performing a series of readback tests. This test DOES modify
* certain registers, so a reinitialization will be required. This test is
* recommended only for development use.
*
* @param[in] pProslic - This should point to the channel that is to be verified.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error amd will typically return back
* @ref RC_SPI_FAIL if a SPI failure occured.
*/
int ProSLIC_VerifyControlInterface (proslicChanType_ptr pProslic);
/** @addtogroup PSTN_CHECK PSTN Check
* @{
*/
/**
* @brief
* Allocates memory for a PSTN check object. One channel object is needed per
* ProSLIC channel.
*
* @param[in,out] pstnCheckObj - pointer to the object that is to be initialized.
*
* @retval 0 = OK
*/
int ProSLIC_CreatePSTNCheckObj(proslicPSTNCheckObjType_ptr *pstnCheckObj);
/**
* @brief
* Allocates memory for a differential PSTN check object. One channel object is needed per
* ProSLIC channel.
*
* @param[in,out] pstnCheckObj - pointer to the object that is to be initialized.
*
* @retval 0 = OK
*/
int ProSLIC_CreateDiffPSTNCheckObj(proslicDiffPSTNCheckObjType_ptr *pstnCheckObj);
/**
* @brief
* Destroys a PSTN check object and deallocates memory.
*
* @param[in] pstnCheckObj - object to deallocate.
*
* @retval 0 = OK
*/
int ProSLIC_DestroyPSTNCheckObj(proslicPSTNCheckObjType_ptr *pstnCheckObj);
/**
* @brief
* Destroys a differential PSTN check object and deallocates memory.
*
* @param[in] pstnCheckObj - object to deallocate.
*
* @retval 0 = OK
*/
int ProSLIC_DestroyDiffPSTNCheckObj(proslicDiffPSTNCheckObjType_ptr *pstnCheckObj);
/**
* @brief
* Initialize pstnCheckObj structure memebers
*
* @param[in] pstnCheckObj - which object to initialize
* @param[in] avgThresh - Average current threshold that indicates a PSTN is present (uA).
* @param[in] singleThresh - Single current threshold that indicates a PSTN is present (uA).
* @param[in] samples - number of samples to collect
* @retval 0 = OK
*/
int ProSLIC_InitPSTNCheckObj(proslicPSTNCheckObjType_ptr pstnCheckObj, int32 avgThresh, int32 singleThresh, uInt8 samples);
/**
* @brief
* This function initializes a differential PSTN detection object.
*
* @param[in,out] pstnDiffCheckObj - object to be initialized
* @param[in] preset1 - DC Feed preset to be used for first loop I/V measurement
* @param[in] preset2 - DC Feed preset to be used for second loop I/V measurement
* @param[in] entry_preset - restore_preset DC Feed preset that is restored after PSTN check is complete.
* @param[in] femf_enable - Flag to enable OPEN state hazardous voltage measurement (0 = disabled, 1 = enabled)
* @retval 0 = OK
*/
int ProSLIC_InitDiffPSTNCheckObj(proslicDiffPSTNCheckObjType_ptr pstnDiffCheckObj, int preset1, int preset2, int entry_preset, int femf_enable);
/**
* @brief
* This function monitors longitudinal current (average and single sample) to quickly identify
* the presence of a live PSTN line. Sufficient polling needs to occur in order to quickly determine
* if a PSTN line is preset or not.
*
* @param[in] pProslic - which channel to run this test on.
* @param[in] pPSTNCheck - the initialized data structure that contains the intermediate results of this test.
* @retval 0 = no PSTN detected/thresholds have not been exceeded, 1 = PSTN detected, state machine reset.
*
* @note
* If wanting to restart the test, one will need to call @ref ProSLIC_InitPSTNCheckObj again. However, if the
* number of samples exceeds the buffer then the function will "wrap".
*/
int ProSLIC_PSTNCheck(proslicChanType *pProslic, proslicPSTNCheckObjType *pPSTNCheck);
/**
* @brief
* This function monitors for a foreign voltage (if enabled) and measures the differential I/V
* characteristics of the loop at 2 unique settings to detect a foreign PSTN. It is assumed that polling will
* occur at the configured value found in @ref PSTN_DET_POLL_RATE.
*
* @param[in] pProslic - channel to be monitored
* @param[in,out] pPSTNCheck - pointer to an initialzed structure that is used by the function to
* store state information.
* @retval @ref RC_NONE - test is in progress, @ref RC_COMPLETE_NO_ERR - test complete, no errors, @ref RC_PSTN_OPEN_FEMF - detected foreign voltage, RC_CHANNEL_TYPE_ERR = a non-ProSLIC device was called to perform this function
*/
int ProSLIC_DiffPSTNCheck(proslicChanType *pProslic, proslicDiffPSTNCheckObjType *pPSTNCheck);
/** @} PSTN_CHECK */
/** @} DIAGNOSTICS*/
/*****************************************************************************/
/** @defgroup PROSLIC_DCFEED DC Feed Setup and control
* @{
*/
/**
* @brief
* Configures the DC feed from a preset.
*
* @param[in] hProslic - which channel to configure
* @param[in] preset - the preset to use
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
* @note This function can be disabled by @ref DISABLE_DCFEED_SETUP
*/
int ProSLIC_DCFeedSetup (proslicChanType_ptr hProslic,int preset);
int ProSLIC_DCFeedSetupCfg (proslicChanType_ptr hProslic, ProSLIC_DCfeed_Cfg *cfg, int preset);
/**
* @brief
* This function allows one to adjust the DC open circuit voltage level dynamically. Boundary checking is done.
*
* @note This function does NOT modify the register sets needed, it calculates the correct values and stores
* them in the correct preset. Use @ref ProSLIC_DCFeedSetup to program the device with the new values.
*
* @param[in] pProslic - which channel to configure
* @param[in] v_vlim_val - absolute voltage level
* @param[in] preset - DC Feed preset to be modified.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
* @sa ProSLIC_dbgSetDCFeedIloop ProSLIC_DCFeedSetup
*/
int ProSLIC_dbgSetDCFeedVopen (proslicChanType *pProslic, uInt32 v_vlim_val, int32 preset);
/**
* @brief
* This function allows one to adjust the loop current level dynamically. Boundary checking is done.
*
* @note This function does NOT modify the register sets needed, it calculates the correct values and stores
* them in the correct preset. Use @ref ProSLIC_DCFeedSetup to program the device with the new values.
*
* @param[in] pProslic - which channel to configure
* @param[in] i_ilim_val - loop current level
* @param[in] preset - DC Feed preset to be modified.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
* @sa ProSLIC_dbgSetDCFeedVopen ProSLIC_DCFeedSetup
*/
int ProSLIC_dbgSetDCFeedIloop (proslicChanType *pProslic, uInt32 i_ilim_val, int32 preset);
/**
* @brief
* This function allows one to enable/disable power savings mode found on some of the chipsets. This allows one
* to change the default value set in the GUI config tool.
*
* @param[in] pProslic - which channel to configure
* @param[in] pwrsave - power savings mode enabled or disabled - value expected: @ref PWRSAVE_DISABLE or @ref PWRSAVE_ENABLE
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*
*/
int ProSLIC_SetPowersaveMode(proslicChanType *pProslic, int pwrsave);
/** @} PROSLIC_DCFEED */
/*****************************************************************************/
/** @defgroup MISC MISC. routines
* @{
*/
/**
* @brief
* Implements message waiting indicator
*
* @details
* Message waiting (neon flashing) requires modifications to vbath_expect and slope_vlim.
* The old values are restored to turn off the lamp. The function assumes the channels
* are all configured the same. During off-hook event lamp must be disabled manually.
*
* @param[in] hProslic - channel to modify
* @param[in] lampOn - 0 = lamp is off, 1 = lamp is on.
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*/
int ProSLIC_MWI (proslicChanType_ptr hProslic,uInt8 lampOn);
/**
* @brief
* This function initiates PLL free run mode.
*
* @param[in] hProslic - which channel to modify
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*/
int ProSLIC_PLLFreeRunStart (proslicChanType_ptr hProslic);
/**
* @brief
* This function terminates PLL free run mode.
*
* @param[in] hProslic - which channel to modify
* @retval int - error from @ref errorCodeType @ref RC_NONE indicates no error.
*/
int ProSLIC_PLLFreeRunStop (proslicChanType_ptr hProslic);
/**
* @brief
* This function returns back a string with the current version of the
* ProSLIC API.
*
* @details
* The string is in the following format MM.mm.vv[.rcX] format, where
* MM is the major number, mm is the minor number and vv is the sub-minor number.
* If this is a release candidate, a .RCx is tacked on - such as RC1 for release
* candidate 1.
*
* @retval char * - returns back a constant string.
*/
char *ProSLIC_Version(void);
/** @} MISC */
/** @} */
#endif /*end ifdef PROSLIC_H*/