eid.c

Reference Implementation of G.711 standard and other voice codecs

/*                                                      04.08.93  - V2.3
  =============================================================================

                          U    U   GGG    SSSS  TTTTT
                          U    U  G       S       T
                          U    U  G  GG   SSSS    T
                          U    U  G   G       S   T
                           UUU     GG     SSS     T

                   ========================================
                    ITU-T - USER'S GROUP ON SOFTWARE TOOLS
                   ========================================


       =============================================================
       COPYRIGHT NOTE: This source code, and all of its derivations,
       is subject to the "ITU-T General Public License". Please have
       it  read  in    the  distribution  disk,   or  in  the  ITU-T
       Recommendation G.191 on "SOFTWARE TOOLS FOR SPEECH AND  AUDIO 
       CODING STANDARDS".
       =============================================================


MODULE:         EID.C, ERROR INSERTION DEVICE

ORIGINAL BY:    

                Rudolf Hofmann                                
                Advanced Development Digital Signal Processing
                PHILIPS KOMMUNIKATIONS INDUSTRIE AG           
                Kommunikationssysteme                         
                Thurn-und-Taxis-Strasse 14                    
                D-8500 Nuernberg 10 (Germany)                 
                                                              
                Phone : [phone]                      
                FAX   : [phone]                      
                EMail : [e-mail]

DESCRIPTION:      Error Insertion Device.
                  - Generates random or bursty error patterns
                    with bit error rates from 0.00% up to 50%
                  - disturbes data bits according these error patterns
                  - allows implementation of "frame erasure" with a
                    certain frame erasure rate (also random or bursty
                    nature selectable)

NOTES:         a) The format of I/O-data is explained in the header of
                  each function. There is also some information given 
                  concerning the algorithm of the function.

               b) Generation of bit error pattern and disturbance of the
                  individual bits have been splitted up into two functions.
                  This allows the load of error patterns (eg, from a file), 
                  which have been generated by other software
                  (i.e. with respect to certain channel models)

               c) The generation of the error patterns here is done with
                  the aid of a Gilber Elliot channel model, which allows the
                  production of random errors as well as bursty errors
                  by defining a simple 'correlation factor' (gamma).
                  For more details see description of function
                  "GEC_init" (see also separate ITU-T document).

FUNCTIONS       : - open_eid (double ber, double gamma)
                     Creates a struct containing arrays and variables
                     for the EID. Initializes the error pattern generator,
                     which produces error patterns defined by ber, gamma:
                     Input: ber   = bit error rate (0 =<  ber  < 0.5 )
                     Input: gamma = burst factor   (0 =< gamma < 0.99)
                                    the bursty nature of the error
                                    pattern increases with gamma
                                    (gamma = 0: equally distributed errors
                                     gamma = 1: totally bursty errors)

                  - BER_generator (SCD_EID *EID, long lseg, short *EPbuff)
                     Generates a bit error sequence with properties,
                     defined by "open_eid".
                     Input : EID    = pointer to EID-struct
                     Input : lseg   = number of error bits to be generated
                                      in one call.
                     Output: EPbuff = array, containing the error pattern

                  - BER_insertion (long lseg, short *ibuff,
                                              short *obuff, short *EPbuff)
                     Disturbes the input data bits according the error
                     pattern, stored in EPbuff[].
                     Input : lseg    = number of data bits in ibuff[]
                     Input : ibuff[] = array, containing "lseg" data bits
                                       (dimension: lseg+1;
                                        ibuff[0] = SYNC-word )
                     Input : EPbuff[]= array, containing the error pattern
                                       (dimension: lseg)
                     Output: obuff[] = array, containing the disturbed
                                       input data bits
                                       (dimension: lseg+1;
                                        obuff[0] = SYNC-word )
		  **	 
		  **  Include the following routine
		  **  G. Schroeder 04.08.1993
		  **	 
                  -  FER_generator_random(SCD_EID *EID)
                     Frame erasure module.
                     Input : EID     = pointer to EID-struct

                  - FER_module(SCD_EID *EID, long  lseg, short *ibuff,
                                                         short *obuff)
                     Frame erasure module.
                     Input : EID     = pointer to EID-struct
                     Input : lseg    = number of data bits in ibuff[]
                     Input : ibuff[] = array, containing "lseg" data bits
                                       (dimension: lseg+1;
                                        ibuff[0] = SYNC-word )
                     Output: obuff[] = array, containing the input data
                                       bits or all bits erased
                                       (dimension: lseg+1;
                                        obuff[0] = SYNC-word or
                                                   marked SYNC-word)
                  - close_eid (SCD_EID *EID)
                     Frees memmory allocated to the EID state variables' 
                     buffer. 

		   - open_burst_eid(long index);

		   - FER_generator_burst(BURST_EID *state);
                   - reset_burst_eid(BURST_EID *burst_eid);

 HISTORY:
  28.Feb.92 v1.0 1st UGST version
  20.Apr.92 v2.0 Modifications on the RNG
  24.Apr.92 v2.1 Modifications for portability issues and inclusion of
                 the PORT_TEST compilation clausule.
  24.Apr.92 v2.2 Inclusion of close_eid.
  04.Aug.93 v2.3 Inclusion of burst frame erasure routines by 
                 <[e-mail]>
  06.Jun.95 v2.4 Changed self-documentation of module BER_insertion to 
                 align the softbit definitions of the EID module 
                 with the EID hardware and Rec.G.192. Code not
                 changed <[e-mail]>
  15.Aug.97 v2.5 Added a function to reset the Belcore mode state
                 variable, reset_burst_eid() <simao>
  =============================================================================
*/

 
 
/* ********************* BEGIN OF EXAMPLES ON USAGE *********************** */
 
/* ==========================================================================
   Below two example programs are presented, how to use the EID-functions,
   one for insertion of bit errors and the other one for frame erasure.

   VERY IMPORTANT NOTE: If the internal EID-states are not saved to file at 
      the end of the program, identical error patterns will be produced when 
      the program is re-started.
      Since file-I/O must be implemented by the user, examples for this
      are given in the EIDDEMO.C demo program.

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

/*============================================================================*/
/*                   Example Program for BIT ERROR INSERTION                  */
/*============================================================================*/
#ifdef A_Z_R_J_B_L_X                    /* to avoid compilation of examples */

main(int argc, char** argv)
{
   SCD_EID *BEReid;                     /* pointer to EID-structure */
   char ifile[128],ofile[128];          /* input/output file names */
   FILE *ifilptr,*ofilptr;              /* input/output file pointer */
   int    EOF_detected;
 
   double ber,gamma;                    /* bit error rate, burst factor */
   long   lseg,lread;                   /* length of one transmitted frame */
   double ber1;                         /* return values from BER_generator */
   double dstbits;                      /* count total distorted bits */
   double prcbits;                      /* count number of processed bits */

   short *xbuff,*ybuff,shvar;           /* pointer to bit-buffer */
   short *EPbuff;                       /* pointer to error pattern-buffer */
   short SYNCword,i;
 
    clock_t t1,t2;
    double t;
 
/* ------------------------------- Statements ------------------------------- */
 
   .... Put your statements here ....
 
  GET_PAR_S(1,"_File with input bit stream: ............... ",ifile);
   ifilptr = fopen(ifile,RB);           /* open input file */
   if (ifilptr==NULL)
      HARAKIRI("    Could not open input file",1);
 
        /* ------------------------------------------------------------------ */
        /* Find SYNC-word and frame length on file */
        /* ------------------------------------------------------------------ */
        lread = fread(&SYNCword,2,1,ifilptr);
        if (SYNCword!=(short)0x6B21)
          HARAKIRI("    First word on input file not the SYNC-word (0x6B21)",1);
        lseg = 0;
        i    = 0;
        while(lseg==0)
        {
            lread = fread(&shvar,2,1,ifilptr);
            if (lread==0)
               HARAKIRI("    No next SYNC-word found on input file",1);
            if (shvar==SYNCword)
                lseg=i;
            i++;
        }
        fseek(ifilptr,0L,0);            /* filepointer back */
 
 
  GET_PAR_S(2,"_File for disturbed bitstream: ............. ",ofile);
   ofilptr = fopen(ofile,WB);
   if (ofilptr==NULL)
      HARAKIRI("    Could not create output file",1);
 
 
/* -------------------------------------------------------------------------- */
/*                       Initialize EID (bit error rate) */
/* -------------------------------------------------------------------------- */
  GET_PAR_D(3,"_bit error rate     (0.0 ... 0.50): ........ ",ber);
  GET_PAR_D(4,"_burst factor       (0.0 ... 0.99): ........ ",gamma);
 
     BEReid = open_eid(ber,gamma);      /* Open EID */
     if (BEReid==(SCD_EID *)0)
        HARAKIRI("    Could not create EID for bit errors!?",1);
 
 
/* -------------------------------------------------------------------------- */
/*                       Allocate memory for I/O-buffer */
/* -------------------------------------------------------------------------- */
  printf("_found frame length on input file: ......... %d\n",lseg);
 
/* -------------------------------------------------------------------------- */
/* a) buffer for input bit stream: */
    xbuff = (short *)malloc((1+lseg)*sizeof(short));
    if (xbuff==(short *)0)
       HARAKIRI("    Could not allocate memory for input bit stream buffer",1);
 
/* -------------------------------------------------------------------------- */
/* b) buffer for output bit stream: */
    ybuff = (short *)malloc((1+lseg)*sizeof(short));
    if (ybuff==(short *)0)
       HARAKIRI("    Could not allocate memory for output bit stream buffer",1);
 
/* -------------------------------------------------------------------------- */
/* c) buffer for storing the error pattern: */
    EPbuff = (short *)malloc((lseg)*sizeof(short));
    if (EPbuff==(short *)0)
       HARAKIRI("    Could not allocate memory for error pattern buffer",1);
 
/* -------------------------------------------------------------------------- */
/*                           Now process input file */
/* -------------------------------------------------------------------------- */
/* initialize counters fro computing bit error rate/frame erasure rate */
    dstbits = 0.0;                      /* number of distorted bits */
    prcbits = 0.0;                      /* number of processed bits */

    /* ---------------------------------------------------------------------- */
    /*      Read file with input bit stream (segments of lenght "lseg+1") */
    /* ---------------------------------------------------------------------- */
    EOF_detected=0;                     /* Flag, to mark END OF FILE */
    t1 = clock();                       /* measure CPU-time */
 
    while( (lread=fread(xbuff,2,lseg+1,ifilptr)) == lseg+1)
    {
      if (xbuff[0]==SYNCword && EOF_detected==0)
      {
        /* ------------------------------------------------------------------ */
        /*                       Generate Error Pattern */
        /* ------------------------------------------------------------------ */
        ber1 = BER_generator(BEReid, lseg,EPbuff);
          dstbits += ber1;              /* count number of disturbed bits */
          prcbits += (double)lseg;      /* count number of processed bits */

        /* ------------------------------------------------------------------ */
        /*     Modify input bit stream according the stored error pattern */
        /* ------------------------------------------------------------------ */
        BER_insertion(lseg+1,xbuff,ybuff,EPbuff);
 
 
        /* ------------------------------------------------------------------ */
        /*               Write disturbed bits to output file */
        /* ------------------------------------------------------------------ */
        lread=fwrite(ybuff,2,lseg+1,ofilptr);
      }
 
      else                              /* if the next SYNC-word is missed */
      {
         EOF_detected=1;
      }
    }
 
    if (EOF_detected==1)
        printf("   --- end of file detected (no SYNCword match) ---\n");
    printf("\n");
 
    t2 = clock();
    t  = (t2 - t1) / (double) CLOCKS_PER_SEC;
    printf("CPU-time %f sec\r\n\n",t);
 
/* -------------------------------------------------------------------------- */
/*                 Print message with measured bit error rate */
/* -------------------------------------------------------------------------- */
    if (prcbits>0)
    {
        printf("measured bit error rate    : %f  (%ld of %ld bits distorted)\n",
                dstbits/prcbits,(long)dstbits,(long)prcbits);
    }
 
    exit(0);
}
 
 
 
 
 
 
 
 
 
/* ========================================================================== */
/*                      Example program for FRAME ERASURE                     */
/* ========================================================================== */
/* -------------------------------------------------------------------------- */
/*                                Main Program                                */
/* -------------------------------------------------------------------------- */

main(int argc, char** argv)
{
   SCD_EID *FEReid;                     /* pointer to EID-structure */
   char ifile[128],ofile[128];          /* input/output file names */
   FILE *ifilptr,*ofilptr;              /* input/output file pointer */
   int    EOF_detected;
 
   double fer,gamma;                    /* frame erasure rate; burst factor */
 
   long   lseg,lread;                   /* length of one transmitted frame */
   double fer1;                         /* return value from FER_insertion */
   double ersfrms;                      /* total distorted frames */
   double prcfrms;                      /* number of processed frames */
   short *xbuff,*ybuff,shvar;           /* pointer to bit-buffer */
   short SYNCword,i;
 
   clock_t t1,t2;
   double t;
 
/* ------------------------------- Statements ------------------------------- */
 
  .... Put your statements here ....
 
  GET_PAR_S(1,"_File with input bit stream: ............... ",ifile);
   ifilptr = fopen(ifile,RB);
   if (ifilptr==NULL)
      HARAKIRI("    Could not open input file",1);
        /* ------------------------------------------------------------------ */
        /* Find SYNC-word and frame length on file */
        /* ------------------------------------------------------------------ */
        lread = fread(&SYNCword,2,1,ifilptr);
        if (SYNCword!=(short)0x6B21)
          HARAKIRI("    First word on input file not the SYNC-word (0x6B21)",1);
        lseg = 0;
        i    = 0;
        while(lseg==0)
        {
            lread = fread(&shvar,2,1,ifilptr);
            if (lread==0)
               HARAKIRI("    No next SYNC-word found on input file",1);
            if (shvar==SYNCword)
                lseg=i;
            i++;
        }
        fseek(ifilptr,0L,0);            /* filepointer back */
 
 
  GET_PAR_S(2,"_File for disturbed bitstream: ............. ",ofile);
   ofilptr = fopen(ofile,WB);
   if (ofilptr==NULL)
      HARAKIRI("    Could not create output file",1);
 
  GET_PAR_D(3,"_frame erasure rate (0.0 ... 0.50): ........ ",fer);
  GET_PAR_D(4,"_burst factor       (0.0 ... 0.99): ........ ",gamma);
 
/* -------------------------------------------------------------------------- */
/*                               Initialize EID */
/* -------------------------------------------------------------------------- */