/*------------------------------------------------------------------------*
*                                                                         *
*   THIS IS AN UNPUBLISHED WORK CONTAINING CONFIDENTIAL AND PROPRIETARY   *
*   INFORMATION.  IF PUBLICATION OCCURS, THE FOLLOWING NOTICE APPLIES:    *
*      "COPYRIGHT 2001 MIKET DSP SOLUTIONS, ALL RIGHTS RESERVED"          *
*                                                                         *
*-------------------------------------------------------------------------*/ 
/* 	
	Generic 'any single/dual' Tone Generator (TG), 
	it suits for DTMF and call progress tones, 
	or whatever, having no more than 2 freqs.
	
	TG adds tone to the output buffer, thus allowing extensions 
	to more freqs per tone
	and mixing with voice messages (required for call progress).
	The same approach (and mostly the same code) can be used for FSK, etc.
	
	Phase continuity during frequency change is preserved 
	(needed for warbles or other TIA/EIA-464 call progress tones, 
	like intercept tone, which contains alternating freq 440 and 620 Hz, 
	each ON for 0.16..0.3s).
	
	Phase noise, non-linear distortions 
	(really they are mirrored freq components): 
		-50 dB relative to signal level, 
	what hides artefacts below mu/A-low distortions level.

	Tone generator uses sine lookup table.
	If a [usually large] sine table is masked in ROM : use it !!!
	Spectrum improves when table grows, at least 3dB per size doubling.
	
	Contrary to oscillator and matrix rotation methods,	
	this approach provides all of: 
		- stable amplitude,
		- continuous phase (and so ability to sweep/alter frequencies),
		- lowest control() overhead 
			(no need to compute precise sin() and cos() 
			 during start-up (or any change in content),
		- low mips,
	on account of
		- large table space;
		- not-so clean spectrum;
			
	TG accepts as config input per digit / tone pair:
    	- frequencies (4000Hz (or Fsampling/2) = 32767) per frequency, 
    	- levels (FS = +3.17 dBm = 32767) per frequency
    	- durations (10 or 5ms resolution (re: ITG_FR_SZ)) of 
        	- silence-before (might be 0), 
        	- dual-tone-itself (-1 if infnite), 
        	- silence-after (might be 0).

    The simplicity of control aids in keeping control overhead 
    (on both sides: caller and callee) low. 
    It is important because in most cases it adds to peak periodic execution,
    effectively rising MIPS requirements. 
    If not accounted for, it can drive entire DSP out of MIPS budget, 
    what is not much fun if it happens in field once upon a time...
    
	Higher level functionality, as string dialing if needed 
	shall be extra - it is VERY system dependant,
	I am not aware of a 'generic' format that will work 
	for all applications (I am aware of...).
 
*/
#ifndef ITG_
#define ITG_    

#include <std.h>
#include <ialg.h>

/*--------------------- public defs ---------------------------------------*/ 

#define ITG_FR_SZ 	(40) /* FRAME SIZE */

typedef struct ITG_Obj {
    struct ITG_Fxns *fxns;
} ITG_Obj;

typedef struct ITG_Obj *ITG_Handle;

/*
 *  ======== ITG_Params ========
 *  This structure defines the parameters necessary to create an
 *  instance of a TG object.
 *
 */                 
 

typedef struct ITG_Params {
    Int size;           /* sizeof the whole parameter struct */
} ITG_Params;



/*
 *  ------- control interface ---------
 *
 * use it while calling algControl()
 */                          
 
/* definition of Cmd param */ 
#define ITG_CMD_NONE  (0)
#define ITG_CMD_RESET (1)
#define ITG_CMD_TONE  (2)

/* definition of Status param */
typedef struct ITG_tTone
{
	Int sAmp;
	Int sFreq; /* 32768 -> 4000 Hz, 1/2 of sampling freq */
} ITG_tToneCfg;

enum /* reported state of generator */
{
	ITG_ST_IDLE = 0,
	ITG_ST_PRE_SILENCE,
	ITG_ST_SIGNAL,
	ITG_ST_POST_SILENCE,

    ITG_ST_MAX
};


typedef struct ITG_Status {
    Int size;           /* sizeof the whole parameter struct */
    
    Int State;					/* out */    
    
                                /* the rest: in */
    Int sPreSilenceDuration;    /* all durations in integer frame sizes, 10|5ms */
    Int sSignalDuration;      	/* -1 = infinite */
    Int sPostSilenceDuration;
    ITG_tToneCfg Lo;
    ITG_tToneCfg Hi;

} ITG_Status;


/*
 *  ======== ITG_Fxns ========
 *  All implementation's of TG must declare and statically 
 *  initialize a constant variable of this type.
 *
 *  By convention the name of the variable is TG_MIKET_ITG, where
 *  MIKET is the vendor name.
 */
typedef struct ITG_Fxns {
    IALG_Fxns   ialg;
    /* functions returns the state of the tone gen. if 0 (=IDLE) - > ready for the next tone */
    Int         (*algProcess)(IALG_Handle handle, Int pOut[]);
} ITG_Fxns;

/*--------------------- local defs ----------------------------------------*/ 
/*--------------------- public vars ---------------------------------------*/
/*--------------------- local vars ----------------------------------------*/
/*--------------------- local functions -----------------------------------*/
/*--------------------- public  functions ---------------------------------*/

#endif  /* ITG_ */