eid.c

Reference Implementation of G.711 standard and other voice codecs

        xbuff: ... buffer with undisturbed input G.192-compliant 
                   soft bitstream (length= lseg)
        ybuff: ... buffer with disturbed output G.192-compliant 
                   soft bitstream (length= lseg)

        Return value:
        ~~~~~~~~~~~~~
        Returns (double)1 if the current frame has been erased, and
        (double)0 otherwise. 

        Author:
        ~~~~~~~
        Simao Ferraz de Campos Neto
        Comsat Laboratories                  Tel:    [phone]
        22300 Comsat Drive                   Fax:    [phone]
        Clarksburg MD 20871 - USA            E-mail: [e-mail]

        History:
        ~~~~~~~~
        07.Mar.96 v1.0 Created based on the STL92 version of this function
                       by <[e-mail]>, which did not comply with
                       the bitstream data representation in Annex B of
                       G.192. <[e-mail]>

 ============================================================================ 
*/
double FER_module_stl96(EID, lseg,xbuff,ybuff)
SCD_EID *EID; 
long  lseg; 
short *xbuff; 
short *ybuff; 
{
  long i,n;                        /* value of random generator */
  double RAN,fer;
 

  /* Get next random number */
  RAN = EID_random(&(EID->seed));
 
  /* See if another channel state has to be entered */
  for (n=0; n<EID->nstates; n++)
  {
    if (RAN < EID->matrix[EID->current_state][n])
    {
      EID->current_state = n; /* go to the selected state */
      n = EID->nstates;       /* -> aborts loop */
    }
  }
 
  /*
   * ......... Compute bit error in current state .........
   */

  /* Get next random number */
  RAN = EID_random(&(EID->seed));
 
  /* if random number below the threshold (bit error rate in current state), 
     erase current frame totally */
  if (RAN < EID->ber[EID->current_state])
  {
    /* Modify SYNC-word and copy frame length word */
    ybuff[0] = xbuff[0] & 0x0000FFF0; 
    ybuff[1] = xbuff[1];

    /* set all bits in current frame to 0x0000 (which means 'not good - 
       not bad') */
    for (i=2; i<lseg; i++)
      ybuff[i] = (short)0x0000;    
    fer = 1.0;
  }
  else
  {
    /* otherwise copy SYNC-word and frame length word into output buffer*/
    ybuff[0] = xbuff[0];
    ybuff[1] = xbuff[1];

    /* ... and store data remaining data */
    for (i=2; i<lseg; i++)
      ybuff[i] = (short)(0x00FF) & (xbuff[i]);
    fer = 0.0;
  }

  /* Return the frame erasure flag */
  return(fer);
}
/* ....................... End of FER_module_stl96() ....................... */
 

/*
  ============================================================================ 

        double EID_random (unsigned long *seed);
        ~~~~~~~~~~~~~~~~~

        Description:
        ~~~~~~~~~~~~

        Returns a new random number, generated a linear congruential
        sequence (LCS) generator. See: Knuth, D.E. 1981: "Seminumerical
        Algorithms" vol.2 of The Art of Computer Programming; Reading,
        Mass.; Addison-Wesley.

        Parameters:    
        ~~~~~~~~~~~  
        seed: ... long seed.

        Return value:
        ~~~~~~~~~~~~~
        Returns a random number as double in the range 0..1.

        Author: <[e-mail]>
        ~~~~~~~

        History:
        ~~~~~~~~
        28.Feb.92 v1.0 Release of 1st version <[e-mail]>
        20.Apr.92 v2.0 Change of polinomial generator to LCG
                       <[e-mail]>
	26.Jan.98 v3.0 Corrected bug for 64-bit operating systems (where 
                       longs have 64, not 32 bits). Implemented by
                       <[e-mail]>, after bug reported
                       by <[e-mail]>

 ============================================================================
*/
double EID_random(seed)
unsigned long *seed;
{
  /* Size in bits (=size in bytes * 8) for long variables*/
   static double bits_in_long = sizeof(long) * 8;

   /* Update RNG */
   *seed = ((unsigned long)69069L * (*seed) +1L);

   /* Return random number as a double */
#ifdef WAS
   return(pow((double)2.0, (double)-32.0) * (double)(*seed));
#else
   return(pow((double)2.0, -bits_in_long) * (double)(*seed));
#endif
}
/* ....................... End of EID_random() ....................... */ 
 
 
/*
  ============================================================================ 

        long GEC_init (SCD_EID *EID, double  ber, double  gamma);
        ~~~~~~~~~~~~~

        Description:
        ~~~~~~~~~~~~

        Initialise Gilbert Elliot channel model for generating bit 
        error sequences. A detailed description is given in a separate
        ITU-T document, and here only a short overview is given: 

                                       P
                  +----+   +----------->----------+   +----+
                  |    +---^-+                  +-V---+    |
              1-P |    |  G  |                  |  B  |    | 1-Q
                  |    +---^-+                  +-V---+    |
                  +--->+   +-----------<----------+   +<---+
                                       Q

        The model provides two different channel states, GOOD (G) and
        BAD (B). If the channel is in state G, the bit error rate is
        P_G, in state B the bit error rate is P_B. The channel state
        changes from G to B with probability P, and from B to G with
        probability Q. The probability, that the channel remains in the
        current state is then 1-P and 1-Q, respectively. 

        If the mean value of the bit error rate of the error pattern
        should be "ber", P and Q are computed as follows: 

                                     /      (P_B - ber) \ 
                  P   =  (1-gamma) * | 1 -  ----------- |
                                     \      (P_B - P_G) / 

                  Q   =  1  -  P  - gamma

        P_G and P_B are fixed and depend not on the selected bit error
        rate (ber). Here they are fixed as: 

                              P_G = 0.0
                              P_B = 0.5

        With the factor "gamma" the 'correlation' between adjacent bit
        errors can be defined. gamma=0 means 'no correlation' (or random
        error sequence). The more gamma runs to 1.0, the more a
        'correlation' between adjacent bit errors will occur (bursty
        error sequences). 

        Examples: 
        1) gamma = 0: (random errors) 
        
        Compute a bit error sequence of lets say 100000 bits with a bit
        error rate of 0.01. Then N auto-correlation coefficients
        (ACF(tau)) of this sequence are computed and normalized to 
        ACF(0) = 1.0. We can observe, that the remaining coefficients
        ACF(1), ACF(2), ... ACF(N) oscillate around the selected bit
        error rate of 0.01. 

        2) gamma = 0.5: (slightly bursty errors) 
        
        Do the same steps as in Example 1. Now we observe, that the
        coefficients ACF(6), ACF(7), ... ACF(N) oscillate around the
        selected bit error rate of 0.01, whereas ACF(1) ... ACF(5) 
        build a transition region. 

        The more gamma increases, the longer this transition region 
        will be! For example, with gamma=0.9 this transition ends 
        around tau=70. 

        Restrictions: 
        ------------- 
        - gamma < 0.99, otherwise no reasonable 'short term' 
                        error sequences will be produced 
        - ber  =< 0.50, otherwise erroneous sequences may be 
                        produced. 

        Parameters:    
        ~~~~~~~~~~~  
        EID: ..... pointer to EID-struct 
        ber: ..... bit error rate: 0 ... 1.0 
        gamma: ... gamma =   0,    for indepentent errors 
                            >0,<1, for blending independent burst errors 
                         =   1,    for strong burst errors 

        Return value:
        ~~~~~~~~~~~~~
        Returns a 1l on success; 0l if memory allocation failed.

        Author: <[e-mail]>
        ~~~~~~~

        History:
        ~~~~~~~~
        28.Feb.92 v1.0 Release of 1st version <[e-mail]>

 ============================================================================
*/
long GEC_init(EID, ber, gamma)
SCD_EID *EID;
double  ber;
double  gamma;
{
   long i;
    double P,Q,P_G,P_B;
 

   /* simple channel model with only two states: "BAD" and "GOOD" */
    EID->nstates = 2;

  /* Allocate memory for bit error array */
    if ((EID->ber = (double *)malloc(EID->nstates*sizeof(double))) == 0L) 
      return((long)0);
 
  /* Allocate memory for the `transition matrix' */
    if ((EID->matrix = (double **)malloc(EID->nstates*(long)sizeof(double *) )) 
         == (double **)0) 
       return(0L);
 
    for (i=0; i<EID->nstates; i++)
    {
       EID->matrix[i] = (double *)malloc(EID->nstates*(long)sizeof(double));
       if (EID->matrix[i]  == (double *)0) return(0L);
    }
 
  /* Fix P_G to 0.0 and P_B to 0.5 */
    P_G = 0.0;
    P_B = 0.5;

   /* P("GOOD" --> "BAD") */
    P   = (1.0 - gamma) * 2.0 * ber;

   /* P("BAD"  --> "GOOD") */
    Q   = (1.0 - gamma) * (1.0 - 2.0 * ber);

   /* Error rate in state GOOD */
    EID->ber[0]   = P_G;

   /* Error rate in state BAD */
    EID->ber[1]   = P_B;

  /* Fill the transition matrix with normalized thresholds, which must be 
    integer values, since the random generator produces integer values from 
    0x00000000 ... 0x7FFFFFFF.  */

    EID->matrix[0][0]  = (1.0-P);               /* "GOOD" -> "GOOD" */
    EID->matrix[0][1]  =  1.0;                  /* Intervall "GOOD" -> "BAD" */
    EID->matrix[1][0]  =  Q;                    /* Intervall "BAD"  -> "GOOD" */
    EID->matrix[1][1]  =  1.0;                  /* "BAD"  -> "BAD" */
    EID->current_state = 0L;                    /* start with state "GOOD" */
 
  /* Return OK */
    return(1L);
}
/* ....................... End of GEC_init() ....................... */


/*
  ========================================================================== 

        void set_RAN_seed (SCD_EID *EID, unsigned long seed)
        ~~~~~~~~~~~~~~~~~

        Description:
        ~~~~~~~~~~~~

        Auxiliary function to set channel state. Modifying Channel
        Model: random generator's seed.


        Parameters:    
        ~~~~~~~~~~~  
        EID: ......... (In) Pointer to EID-struct 
        seed: ........ (In) new seed for random generator

        Return value:
        ~~~~~~~~~~~~~
        None.

        Author: <[e-mail]>
        ~~~~~~~

        History:
        ~~~~~~~~
        20.Apr.92 v1.0 Release of 1st version <[e-mail]>

 ============================================================================
*/
void set_RAN_seed(EID,seed)                                                  
SCD_EID *EID;
unsigned long seed;
{
  EID->seed = seed;
}
/* ....................... End of set_RAN_seed() ....................... */


/*
  ========================================================================== 

        unsigned long get_RAN_seed (SCD_EID *EID);
        ~~~~~~~~~~~~~~~~~~~~~~~~~~

        Description:
        ~~~~~~~~~~~~

        Auxiliary function to support saving channel states. Get random
        number generator seed.

        Parameters:    
        ~~~~~~~~~~~  
        EID: ... pointer to EID structure with states.

        Return value:
        ~~~~~~~~~~~~~
        Returns the current seed.

        Author: <[e-mail]>
        ~~~~~~~

        History:
        ~~~~~~~~
        20.Apr.92 v1.0 Release of 1st version <[e-mail]>

 ============================================================================ 
*/
unsigned long get_RAN_seed(EID)
SCD_EID *EID;
{
   return(EID->seed);
}
/* ....................... End of get_RAN_seed() ....................... */


/*
  ========================================================================== 

        void set_GEC_matrix (SCD_EID *EID, double threshold, 
        ~~~~~~~~~~~~~~~~~~~  int current_state, int next_state);        

        Description:
        ~~~~~~~~~~~~

        Auxiliary function to support setting channel states. Defines
        Transition Matrix of GEC-model.