spdemo.c

Reference Implementation of G.711 standard and other voice codecs

/*                                                              v3.2 18.Jan.99
  ============================================================================

  SPDEMO.C
  ~~~~~~~~~

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

  DEMO program to show the use of the serialization/
  parallelization functions.

  A input file in the parallel format will be converted to serial
  in the form of 16-bit words whose least significant bits will be
  `1' or `0', as defined below. If the inclusion of a synchronism
  bit is requested, then at the beginning of each data frame a
  sync word (defined below) is added.

                      Bit '0' is represented as '0x007F'
                      Bit '1' is represented as '0x0081'
                      A SYNC-word is defined as '0x6B21'

  This bit definition was chosen to be compatible in the future 
  with the so called 'soft-bit'-format, where the  channel decoder
  outputs probabilities that the  received bit is '0' or '1'. 

  The output bit-stream will then be a binary file where the first
  word on the file is the SYNC-word, followed by LFRAME
  words with the data bits (LFRAME=number of bits in one frame);
  then the next SYNC-word, followed by the next frame, ... and so
  on (if the sync word inclusion is selected). 


  Usage:
  ~~~~~~
  $ spdemo oper finp fout N N1 N2 resolution [sync [just]]
  where:
  oper ......... operation desired:
                 ps input is in parallel format, output is serial
                 sp input is a bit-stream file, output is parallel.
  finp ......... input filename
  fout ......... output filename
  N ............ frame size
  N1 ........... 1st frame to convert
  N2 ........... number of frames from N1 on.
  resolution ... number of bits per sample in input file.
  sync ......... flag for using sync words:
                 1: each frame begin with a SYNC_WORD in the
                    output file; this is the DEFAULT.
                 0: no SYNC_WORDs are used in the output file.
  just ......... flag for choosing justification: 
                 left:  the parallel data is supposed to be right-
		        justified; this is the DEFAULT.
                 right: the parallel data is supposed to be left-
                        justified;
                 (PS: bit-stream 16-bit words are always right-justified!)
  Options:
  -n ............. number of frames to process
  -start ......... first frame to start operation
  -frame ......... payload size in no. of softbits
  -res # ......... bit resolution for file (default 16)
  -left .......... data is left-justified
  -right ......... data is right-justified (the default)
  -nosync ........ don't use sync headers
  -sync .......... use sync headers
  -q ............. quiet operation
  -help, -? ...... display help message

  Compilation:
  ~~~~~~~~~~~~

  VAX/VMS: 
  $ cc spdemo
  $ link spdemo 
  $ spdemo   :== $scd_disk:[scd_dir]spdemo 
  $ spdemo 

  Turbo-C, Turbo-C++: 
  > tcc -ml spdemo
  > spdemo 

  HighC (MetaWare, version R2.32): 
  > hc386 -ml spdemo.c  
  > run386 spdemo 

  Sun-C (BSD-Unix)
  # cc -o spdemo spdemo.c
  # spdemo

        
  Original author: 
  ~~~~~~~~~~~~~~~~
  Simao Ferraz de Campos Neto       
  CPqD/Telebras         		             
  DDS/Pr.11                             Phone : [phone]
  Rd. Mogi Mirim-Campinas Km.118        Fax   : [phone]
  13.088-061 - Campinas - SP (Brazil)   EMail : [e-mail]
                                          
  History
  ~~~~~~~
  20.Mar.92 v1.0 1st release to UGST.
                 <[e-mail]>
  18.May.92 v1.1 Introduction of changes from v1.2 of ugst-utl.c.
                 <[e-mail]>
  14.Apr.94 v1.2 Improved user interface
  06.Jun.95 v2.0 Fixed for correct '1' and '0' softbit definition
                 <[e-mail]>
  20.Aug.97 v3.0 Several changes: <[e-mail]>
                 - Modified code to recognize the G.192 bitstream format
		 - Removed obsolete code portions (memory allocation for
		   input & output files being both parallel - this is
		   prevented by a previous piece of code!)
  16.Jan.98 v3.1 Added conditional compile for Ultrix with cc <simao>
  18.Jan.99 v3.2 Fixed bug in calculation of total no.of samples 
                 to process; fixed a bug in check_sync() which
                 unnecessarily zeroed the frame length variable fr_len
                 causing errors when the user specifies the frame length
		 <simao>
  ============================================================================
*/

/* ..... Generic include files ..... */
#include <stdio.h>                      /* Standard I/O Definitions */
#include <stdlib.h>                     /* for atoi(), atol() */
#include <string.h>                     /* for strstr() */
#include <math.h>                       /* for ceil() */
#include "ugstdemo.h"                   /* general UGST definitions */

/* ..... Specific include files ..... */
#if defined(VMS)		/* for checking file sizes */
#include <stat.h>
#else
#include <sys/stat.h>
#endif

#if defined (unix) && !defined(MSDOS)
/*                 ^^^^^^^^^^^^^^^^^^ This strange construction is necessary
                                      for DJGPP, because "unix" is defined,
				      even it being MSDOS! */
#if defined(__ALPHA)
#include <unistd.h>		/* for SEEK_... definitions used by fseek() */
#else
#include <sys/unistd.h>		/* for SEEK_... definitions used by fseek() */
#endif
#endif


/* ..... Module definition files ..... */
#include "ugst-utl.h"                   /* format conversion functions */


/* ... Local function prototypes ... */
char check_bs_format ARGS((FILE *F, char *file, char *type));
int check_sync ARGS((FILE *F, char *file, char *bs_type, long *fr_len,
		     char *bs_format));
void display_usage ARGS((int level));
/* ......... End of local function prototypes ......... */ 


/* ... Local defines, pseudo-functions ... */
#define is_serial(x) ((x)=='S'||(x)=='s')

#ifdef STL92
#define OVERHEAD 1 /* Overhead is sync word */
#else
#define OVERHEAD 2 /* Overhead is sync word and length word*/
#endif

/* Operating modes */
enum BS_formats {byte, g192, compact, nil};
enum BS_types {NO_HEADER, HAS_HEADER};


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

/*
  --------------------------------------------------------------------------
  char check_bs_format (FILE *F, char *file, char *type);
  ~~~~~~~~~~~~~~~~~~~~

  Function that checks the format (g192, byte, bit) in a given
  bitstream, and tries to guess the type of data (bit stream or frame
  erasure pattern)

  Parameter:
  ~~~~~~~~~~
  F ...... FILE * structure to file to be checked
  file ... name of file to be checked
  type ... pointer to guessed data type (NO_HEADER or HAS_HEADER) in file

  Returned value:
  ~~~~~~~~~~~~~~~
  Returns the data format (g192, byte, bit) found in file.

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

  History:
  ~~~~~~~~
  20.Aug.97  v.1.0  Created.
  -------------------------------------------------------------------------- 
*/
char check_bs_format(F, file, type)
FILE *F;
char *file;
char *type;
{

  short word;
  char ret_val;

  /* Get a 16-bit word from the file */
  fread(&word, sizeof(short), 1, F);

  /* Use some heuristics to determine what type of file is this */
  switch((unsigned)word)
  {
  case 0x7F7F:
  case 0x7F81:
  case 0x817F:
  case 0x8181:
    /* Byte-oriented G.192 bitstream */ 
    *type = NO_HEADER;
    ret_val = byte;
    break;

  case 0x2020:
  case 0x2021:
  case 0x2120:
  case 0x2121:
    /* Byte-oriented G.192 syncs */
    *type = HAS_HEADER;
    ret_val = byte;
    break;

  case 0x007F:
  case 0x0081:
    /* G.192 bitstream in natural order */
    *type = NO_HEADER;
    ret_val = g192;
    break;

  case 0x6B21:
  case 0x6B20:
    /* G.192 sync header in natural order */
    *type = HAS_HEADER;
    ret_val = g192;
    break;

  case 0x7F00:
  case 0x8100:
  case 0x216B:
  case 0x206B:
    /* G.192 format that needs to be byte-swapped */
    fprintf(stderr, "File %s needs to be byte-swapped! Aborted.\n", file);
    exit(8);

  default:
    /* Assuming it is compact bit mode */
   *type = nil; /* Not possible to infer type for binary format! */
    ret_val = compact;
  }

  /* Final check to see if the input bitstream is a byte-oriented G.192
     bitstream. In this case, the first byte is 0x2n (n=0..F) and the
     second byte must be the frame length */
  if ((((unsigned)word>>8) & 0xF0) == 0x20)
  {
     *type = HAS_HEADER;
     ret_val = byte;
  }
  /* Rewind file & and return format identifier */
  fseek(F, 0l, SEEK_SET);
  return(ret_val);
}
/* ...................... End of check_bs_format() ...................... */


int check_sync(F, file, bs_type, fr_len, bs_format)
FILE *F;
char *file;
char *bs_type, *bs_format;
long *fr_len;
{
  long i;
  char sync_header;

  /* Initialize frame length to "unknown" */
  /* *fr_len = 0; */

  /* Get info on bitstream */
  *bs_format = check_bs_format(F, file, bs_type);

  /* If the BS seems to have a header, search for two consecutive
     ones. If it finds, determines which is the frame size */
  if (*bs_type == HAS_HEADER)
  {
    /* The input BS may have a G.192 synchronism header - verify */
    if (*bs_format == g192)
    {
      short tmp[2];

      /* Get presumed first G.192 sync header */
      fread(tmp, sizeof(short), 2, F);
      /* tmp[1] should have the frame length */
      i = tmp[1];
      /* advance file to the (presumed) next G.192 sync header */
      fseek(F, (long)(tmp[1])*sizeof(short), SEEK_CUR);
      /* get (presumed) next G.192 sync header */
      fread(tmp, sizeof(short), 2, F);
      /* Verify */
      if (((tmp[0] & 0xFFF0) == 0x6B20) && (i == tmp[1]))
      {
	*fr_len = i;
	sync_header = 1;
      }
      else
	sync_header = 0;
    }
    else if (*bs_format == byte)
    {
      char tmp[2];

      /* Get presumed first byte-wise G.192 sync header */
      fread(tmp, sizeof(char), 2, F);
      /* tmp[1] should have the frame length */
      i = tmp[1];
      /* advance file to the (presumed) next byte-wise G.192 sync header */
      fseek(F, (long)tmp[1], SEEK_CUR);
      /* get (presumed) next G.192 sync header */
      fread(tmp, sizeof(char), 2, F);
      /* Verify */
      if (((tmp[0] & 0xF0) == 0x20) && (i == tmp[1]))
      {
	*fr_len = i;
	sync_header = 1;
      }
      else
	sync_header = 0;
    }
    else
      sync_header = 0;

    /* Rewind file */
    fseek(F, 0l, SEEK_SET);
  }
  else
    sync_header = 0;

  /* Return info on whether or not a frame sync header was found */
  return(sync_header);
}

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

  Shows program usage.

  History:
  ~~~~~~~~
  20/Aug/1997  v1.0 Created <simao>
  --------------------------------------------------------------------------
*/
#define P(x) printf x
void display_usage(level)
int level;
{
  P(("spdemo.c - version 3.0 of 20/Aug/1997\n"));
 
  P(("  Demo program to convert between serial and parallel data formats.\n"));

  if (level == 1)
  {
    P(("  A input file in the parallel format will be converted to serial\n"));
    P(("  in the form of 16-bit words whose least significant bits will be\n"));
    P(("  `1' or `0', as defined below. If the inclusion of a synchronism\n"));
    P(("  bit is requested, then at the beginning of each data frame a\n"));
    P(("  sync word (defined below) is added.\n"));
    P(("\n"));
    P(("                      Bit '0' is represented as '0x007F'\n"));
    P(("                      Bit '1' is represented as '0x0081'\n"));
    P(("                      A SYNC-word is defined as '0x6B21'\n"));
    P(("\n"));
    P(("  This bit definition was chosen to be compatible in the future \n"));
    P(("  with the so called 'soft-bit'-format, where the  channel decoder\n"));
    P(("  outputs probabilities that the  received bit is '0' or '1'. \n"));
    P(("\n"));
    P(("  The output bit-stream will then be a binary file where the first\n"));
    P(("  word on the file is the SYNC-word, followed by LFRAME\n"));
    P(("  words with the data bits (LFRAME=number of bits in one frame);\n"));
    P(("  then the next SYNC-word, followed by the next frame, ... and so\n"));
    P(("  on (if the sync word inclusion is selected). \n"));
    P(("\n"));
  }

  P(("  Usage:\n"));
  P(("  $ spdemo oper finp fout N N1 N2 resolution [sync [just]]\n"));
  P(("  where:\n"));
  P(("  oper ......... \"ps\": parallel -> serial; \"sp\": serial -> parallel\n"));
  P(("  finp ......... input filename\n"));
  P(("  fout ......... output filename\n"));
  P(("  N ............ frame size\n"));
  P(("  N1 ........... 1st frame to convert\n"));
  P(("  N2 ........... number of frames from N1 on.\n"));
  P(("  resolution ... number of bits per sample in input file.\n"));
  P(("  sync ......... Enable (1) or disable (0) use of sync headers\n"));
  P(("  just ......... data justification: left or right (default)\n\n"));
  P(("  Options:\n"));
  P(("  -n # ........... number of frames to process\n"));
  P(("  -start # ....... first frame to start operation\n"));
  P(("  -frame # ....... payload size in no. of softbits\n"));
  P(("  -res # ......... bit resolution for file (default 16)\n"));
  P(("  -left .......... data is left-justified\n"));
  P(("  -right ......... data is right-justified (the default)\n"));
  P(("  -nosync ........ don't use sync headers\n"));
  P(("  -sync .......... use sync headers\n"));
  P(("  -q ............. quiet operation\n"));
  P(("  -? ............. display short help message\n"));
  P(("  -help, ......... display long help message\n"));

  /* Quit program */
  exit(-128);