gen-patt.c

Reference Implementation of G.711 standard and other voice codecs

/*                                                          15.May.2001 v1.5
   =========================================================================

   gen-patt.c
   ~~~~~~~~~~

   Program Description:
   ~~~~~~~~~~~~~~~~~~~~

   This example program produces bit error pattern files for error
   insertion in G.192-compliant serial bitstreams encoded files. Error
   insertion must be performed by "X-oring" the softbits produced with
   the softbits produced by the speech encoder. The error pattern can
   be generated according to 3 models: Random bit errors (BER), and
   random (FER) and (BFER) burst frame erasure. Three output file
   formats are supported: G.192 serial bitstream, byte-oriented
   softbit serial bitstream, and compact (hard) bit serial bitstream.

   The headerless G.192 serial bitstream format is as described in
   G.192, with the exceptions listed below. The main feature is that
   the softbits and frame erasure indicators are right-aligned at
   16-bit word boundaries (unsigned short): 
   '0'=0x007F and '1'=0x0081, and good/bad frame = 0x6B21/0x6B20

   In the byte-oriented softbit serial bitstream, only the lower byte
   of the softbits defined in G.192 are used. Hence:
   '0'=0x7F and '1'=0x81, and good/bad frame = 0x21/0x20

   In the compact mode, only hard bits are saved. Each byte will have
   information about eight bits or frames. The LBbs will refer to bits
   or frames that occur first in time. Here, '1' means that a bit is
   in error or that a frame should be erased, and a '0', otherwise.

   Valid range for the BER and FER is [0..0.5], and for the BFER is one of
   the 3 values 1%, 3%, and 5%.

   Actual BER/(B)FER values are reported as the ratio of the number of
   disturbed bits/frames over the total number of the bits GENERATED
   (and saved) to file. Note: the number of generated bits/flags is
   the sum of the number od bits/flags processed plus the bits/flags
   skipped in the beginning of the pattern (parameter start of the
   command line, see below).

   Conventions:
   ~~~~~~~~~~~~

   BER: bitstream generated by this program are composed of bits 1/0,
        *without* synchronism headers or any other frame delimitation
        (i.e., only bits affecting the payload are present). Frame
        boundaries are defined by the user's application only. The
        following applies:
        G.192 mode: file will contain either 0x007F (no disturbance) or
                    0x0081 (bit error)
        Byte mode:  file will contain either 0x7F (no disturbance) or
                    0x81 (bit error)
        Compact mode: each bit in the file will indicate whether a
                    disturbance occurred (bit 1) or not (bit 0).
                    Lower order bits apply to bits occurring first
                    in time.

   FER/BFER: bitstream generate by this program is composed only by
        the indication of whether a frame should be erased or not. No
        payload is present. The following applies:
        G.192 mode: file will contain either 0x6B21 (no disturbance) or
                    0x6B20 (frame erasure)
        Byte mode:  file will contain either 0x21 (no disturbance) or
                    0x20 (frame erasure)
        Compact mode: each bit in the file will indicate whether a
                    frame erasure occurred (bit 1) or not (bit 0).
                    Lower order bits apply to bits occurring first
                    in time.

   Usage:
   ~~~~~
   gen-patt [Options] err_pat_bs mode frno start state_f rate

   Where:
   err_pat .. name of error pattern bitstream file
   mode ..... a letter representing one of 4 operating modes: 
              R -> Random Bit Errors
              F -> (Random) Frame Erasure
              B -> Burst Frame Erasure
   frno ..... total number of bits/frames in pattern
   start .... first bit|frame to have errors|erasures introduced
   state_f .. name of an ASCII state variable file. NOTE: The parameters 
              saved in an existing state variable file *OVERRIDE* the
              BER/FER/Gamma values defined by the user in the
              command-line!!!
   rate ..... desired error|erasure rate (according to the mode)

   Options:
   -ber ..... Bit error mode
   -fer ..... Frame erasure mode using Gilbert channel
   -bfer .... Burst frame erasure mode using the Bellcore model
   -rate # .. Desired bit|frame error rate
              BER:  0.00 .. 0.50
              BFER: 0.01, 0.03, or 0.05
              FER:  0.00 .. 0.50
   -gamma # . Correlation for BER|FER modes (0.00 .. 1.00; default: 0)
   -n # ..... Number of bits|frames to be produced
   -start # . First bit|frame to start applying errors
   -byte .... Save error pattern in byte-oriented G.192 format (default)
   -g192 .... Save error pattern in 16-bit G.192 format
   -bit ..... Save error pattern in compact binary format (same as -compact)
   -compact . Save error pattern in compact binary format (same as -bit)
   -reset ... Reset EID state in between iteractions
   -max # ... Maximum number of iteractions
   -tol # ... Max deviation of specified BER/FER/BFER
   -q ....... Quiet operation mode

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

   History:
   ~~~~~~~~
   15.Aug.1997 v.1.0 Created based on gen-patt.c <[e-mail]>
   13.Jan.1999 v.1.1 Corrected bugs associated with the option to skip 
                     initial bits (in BER mode) or frames (in (B)FER
                     mode) was selected <simao>:
                     - was saving 0x007F to file when the skip option
                       was enabled for (B)FER mode -- should be 0x6B21
                     - was saving the wrong number of bits or frame
                       flags
                     - was computing the BER/(B)FER based on the ratio
                       of disturbed bits over processed bits. This is OK
                       for skip==0, but for skip>0, the proper ratio is
                       disturbed/generated (generated is processed plus
                       skipped).
   28.Mar.2000 v1.2    Added warning if module compiled in portability test
                       mode <[e-mail]>
   12.Apr.2000 v1.3  Added consistency check between desired tolerance
                     and specified error/erasure rate and pattern
                     length <simao>
   22.Aug.2000 v1.4  Corrected bug in calculation of minimum tolerance <simao>
   15.May.2001 v1.5  - Corrected bug in initialization of err_patt[] when 
                       treating the skip section of the bit error pattern.
                       Was using memset, which works for chars, to init shorts.
                       Replaced with a for loop. 
                     - Corrected error in logic in the calculation of
                       number of frames skipped, was doing one more than what
                       it should
                     - Revisited calculation of minimum tolerance <simao>
  ========================================================================= */

/* ..... Generic include files ..... */
#include "ugstdemo.h"		/* general UGST definitions */
#include <stdio.h>		/* Standard I/O Definitions */
#include <math.h>
#include <stdlib.h>
#include <string.h>		/* memset */
#include <ctype.h>		/* toupper */

/* ..... Module definition files ..... */
#include "eid.h"		/* EID functions */
#include "eid_io.h"		/* EID state variable I/O functions */
#include "softbit.h"            /* Soft bit definitions */


/* ..... Definitions used by the program ..... */

/* Buffer size definitions */
#define EID_BUFFER_LENGTH 256
#define OUT_RECORD_LENGTH 512

/* Local function prototypes */
char *mode_str ARGS((int mode));
char check_bellcore ARGS((long index));
long run_FER_generator_random ARGS((short *patt, SCD_EID *state, long n));
long run_FER_generator_burst ARGS((short *patt, BURST_EID *state, long n));
void display_usage ARGS((void));



/* *********************************************************************** */
/* ************************* AUXILIARY FUNCTIONS ************************* */
/* *********************************************************************** */

/* 
   -------------------------------------------------------------------------
   Return a string with the EID operating mode:
   B: BFER
   F: FER
   R: BER

   NOTE: in other modules, "mode" is called "type". However, in
         general, the distinction between BFER and FER patterns is not
         meaningful, so the only types distinguished are BER and FER.

   <simao> 15.Aug.97
   -------------------------------------------------------------------------
 */
char           *mode_str (mode)
  char            mode;
{
  mode = toupper (mode);
  return (mode == 'R' ? "BER" : (mode == 'F' ? "FER" : "BFER"));
}
/* ......................... End of mode_str() ......................... */

/* 
   -------------------------------------------------------------------------
   Check if the provided index refers to a valid Bellcore model entry
   (1, 3, 5, 10, 15).

   <simao> 15.Aug.97
   -------------------------------------------------------------------------
 */
char            check_bellcore (index)
  long            index;
{
  if (index == 1 || index == 3 || index == 5 || index == 10 || index == 15)
    return (1);
  else
    return (0);
}
/* ....................... End of check_bellcore() ....................... */


/* 
   -------------------------------------------------------------------------
   long run_FER_generator_random (short *patt, SCD_EID *state, long n)
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   Run the FER_generator_random() function for the specified number of
   times & store the returned frame erasure results in G.192 format into
   an array. Used for improved I/O efficiency.

   Parameter:
   ~~~~~~~~~~
   patt ....... short buffer to store the frame erasure information
   state ...... SCD_EID structure (previously initialized by open_eid)
   n .......... number of times FER_generator_random should be run

   Return value: 
   ~~~~~~~~~~~~~
   The function return the number of erased frames as a long.

   Original author: <[e-mail]>
   ~~~~~~~~~~~~~~~~

   History:
   ~~~~~~~~
   15.Aug.97  v.1.0  Created.
   -------------------------------------------------------------------------
 */
long run_FER_generator_random (patt, state, n)
short *patt;
SCD_EID *state; 
long n;
{
  long fer, i, count;

  for (count=i=0; i<n; i++)
  {
    fer = FER_generator_random (state);
    if (fer)
      count++;
    *patt++ = fer? G192_FER : G192_SYNC;
  }
  return(count);
}
/* .................. End of run_FER_generator_random() .................. */


/* 
   -------------------------------------------------------------------------
   long run_FER_generator_burst (short *patt, BURST_EID *state, long n)
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   Run the FER_generator_burst() function for the specified number of
   times & store the returned frame erasure results in G.192 format into
   an array. Used for improved I/O efficiency.

   Parameter:
   ~~~~~~~~~~
   patt ....... short buffer to store the frame erasure information
   state ...... SCD_EID structure (previously initialized by open_eid)
   n .......... number of times FER_generator_burst should be run

   Return value: 
   ~~~~~~~~~~~~~
   The function return the number of erased frames as a long.

   Original author: <[e-mail]>
   ~~~~~~~~~~~~~~~~

   History:
   ~~~~~~~~
   15.Aug.97  v.1.0  Created.
   -------------------------------------------------------------------------
 */
long run_FER_generator_burst (patt, state, n)
short *patt;
BURST_EID *state; 
long n;
{
  long fer, i, count;

  for (count=i=0; i<n; i++)
  {
    fer = FER_generator_burst (state);
    if (fer)
      count++;
    *patt++ = fer? G192_FER : G192_SYNC;
  }
  return(count);
}
/* .................. End of run_FER_generator_burst() .................. */


/*
   --------------------------------------------------------------------------
   display_usage()

   Shows program usage.

   History:
   ~~~~~~~~
   11/Aug/1997  v1.0 Created <simao>
   --------------------------------------------------------------------------
 */
#define P(x) printf x
void            display_usage ()
{
  P (("gen-patt.c Version 1.5 of 15.May.2001\n"));

  P (("  This example program produces bit error pattern files for error\n"));
  P (("  insertion in G.192-compliant serial bitstreams encoded files. Error\n"));
  P (("  insertion must be performed by \"X-oring\" the softbits produced with\n"));
  P (("  the softbits produced by the speech encoder. The error pattern can\n"));