/* | |
** 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*/ | |