/************************************************************************

European digital cellular telecommunications system
           12200 bits/s speech codec for
     enhanced full rate speech traffic channels

Bit-Exact C Simulation Code
Version 5.1.0 and version for Release 6
June 26, 1996

*************************************************************************/


        These files represent the Enhanced Full Rate GSM Speech Coder Bit
Exact C simulation.  All code is written in ANSI-C.  The system is
implemented as three separate programs:

        coder       speech encoder
        ed_iface    encoder/decoder interface
        decoder     speech decoder

        For encoding using the coder program, the input is a binary
speech file (*.inp) and the output is a binary encoded parameter file
(*.cod).  For decoding using the decoder program, the input is a binary
parameter file (*.dec) and the output is a binary synthesized speech
file (*.out).  Note that the format for the parameter input file required
for decoding (*.dec) is not the same as the format of the parameter file
generated by encoding (*.cod).  The "ed_iface" program will translate an
*.cod file into an *.dec file.

The complete package consists of one DS-HD 3.5" disk, formatted for MS-DOS
operating system.  The disk contains all of the files in the root level.


                            FILE FORMATS:
                            =============
        
File formats are important in the installation process.  If a text
file such as the makefile or a table is in the wrong format, the
program will either not compile, or give incorrect results.

Most of the data on this disk are in "pc" format.  The text files are
intended to be read only by the pc. The binary data files named
spch_dos.* are byte ordered such that they will be read correctly by a
pc.  Those binary data files named spch_unx.* are byte ordered such that
they will be read correctly by most UNIX systems.

If the software is to be run on some other platform than PC,
such as an HP (HP-UX) or a Sun, then some files will need to be modified
before compilation and execution.  The necessary modifications are
described for the HP (HP-UX) and Sun platforms below.

There is more information below on file formats. 


                       INSTALLING THE SOFTWARE
                       =======================


Installing the software on the Sun:
-----------------------------------

1. Getting files from pc disk:
        There are two ways of extracting the files off of the disk:

           a. Using FTP
           b. Mounting the disks and copying the files directly.

        All of the files should be copied to the same directory.

        If using FTP:
        First copy files *.c, *.h, *.tab, *.txt, ts_unx.bat and
        makefile.* using the default (i.e.  not binary) transfer mode.
        Second copy files spch_unx.* using the binary mode (by typing bin).
        Copying files *.c, *.h, *.tab, *.txt, ts_unx.bat and makefile.*
        with the default mode will automatically convert all text files to
        the Sun's file format.  

        If copying the files directly:
        No special instructions.  Be aware though that the text files 
        on the Sun will still be in "pc" format.

2.  Before you make:
        It is assumed that on the Sun the compiler is "cc".  If
        this is not the case modify the symbols:
                CC = cc
                LFLAG =
                CFLAGS = -Xa -DWMOPS=1
        to appropriate settings in makefile.sun. Note that for GCC
        compiler, a separate makefile "makefile.gcc" is provided.

3.  Make:  to make type:
                make -f makefile.sun
           or copy file "makefile.sun" to file "makefile" and make:
                cp makefile.sun makefile
                make


Installing the software on the HP (HP-UX):
------------------------------------------

1. Getting files from pc disk:
        There are two ways of extracting the files off of the disk:

           a. Using FTP
           b. Mounting the disks and copying the files directly.

        All of the files should be copied to the same directory.

        If using FTP:
        First copy files *.c, *.h, *.tab, *.txt, ts_unx.bat and
        makefile.* using the default (i.e.  not binary) transfer mode.
        Second copy files spch_unx.* using the binary mode (by typing bin).
        Copying files *.c, *.h, *.tab, *.txt, ts_unx.bat and makefile.hp
        with the default mode will automatically convert all text files to
        the HP's file format.  

        If copying the files directly:
        No special instructions.  Be aware though that the text files 
        on the HP will still be in "pc" format.

2.  Before you make:
        It is assumed that on the HP the compiler is "cc".  If
        this is not the case modify the symbols:
                CC = cc
                LFLAG =
                CFLAGS = -Aa -DWMOPS=1
        to appropriate settings in makefile.hp. Note that for GCC
        compiler, a separate makefile "makefile.gcc" is provided.
                
3.  Make:  to make type:
                make -f makefile.hp
           or copy file "makefile.hp" to file "makefile" and make:
                cp makefile.hp makefile
                make

Installing the software on the PC:
----------------------------------

1. Getting files from pc disk:
        From the directory where you want the files installed 
        (and assuming the diskette is in drive a), type:

        copy a:\*.* .

2.  Before you make:
        It is assumed that on the PC the compiler is "bcc".  If
        this is not the case modify the symbols:
                CC = bcc
                LFLAG = -ml -N
                CFLAGS = -w -N -ml -DWMOPS=1
        to appropriate settings in makefile.pc. Note that for GCC
        compiler, a separate makefile "makefile.gcc" is provided.
                
3.  Make:  to make type:
                make -f makefile.pc
           or copy file "makefile.pc" to file "makefile" and make:
                copy makefile.pc makefile
                make


More installation information:
------------------------------

When executed, coder and decoder programs display information about
each frame, such as the frame number, total Weighted MOPS (WMOPS)
computational complexity of the encoder or decoder for that frame,
the average WMOPS figure for the frames processed, the observed
worst case WMOPS figure and the observed "worst worst case" figure
of the encoder or decoder for the current frame.

The "worst worst case" figure is the total worst case WMOPS figure
of all subroutines. During execution, each GsmEfr_sub-routine returns its
worst case complexity figure. At the end of processing, the "worst
worst case" figure gives the total of the worst case WMOPS figures
of all of the subroutines.

To switch off the WMOPS display of the codec, set the compile-time
switch "WMOPS" to value 0 in the make file you are using. Note that
when DTX is activated, the worst worst case printout is suppressed,
since it would not give meaningful figures in that case.



                       RUNNING THE SOFTWARE
                       ====================

The usage of the "coder" program is as follows:

   Usage:

   coder  speech_file  bitstream_file  <dtx|nodtx>

Note that running the "coder" program without any command line arguments
will cause it to print out the above Usage message. The DTX is activated
by typing the optional switch "dtx". By default, the DTX is not active.


The usage of the "decoder" program is as follows:

   Usage:

   decoder  bitstream_file  synth_file

Note that running the "coder" program without any command line arguments
will cause it to print out the above Usage message.


The usage of the "ed_iface" program is as follows:

   Usage:

   ed_iface  input  output

Note that running the "ed_iface" program without any command line arguments
will cause it to print out the above Usage message.


Processing the installation verification files on the Sun or HP:
----------------------------------------------------------------

1. Give the installation verification batch file "ts_unx.bat"
   execute permission by typing:
        chmod +x ts_unx.bat

2. Run this file by typing:
        ts_unx.bat

   The compare commands at the end of this file should yield no
   differences.


   Listing of file ts_unx.bat:
   ===========================

   coder spch_unx.inp spchtst.cod
   ed_iface spchtst.cod spchtst.dec
   decoder spchtst.dec spchtst.out

   cmp spchtst.cod spch_unx.cod
   cmp spchtst.dec spch_unx.dec
   cmp spchtst.out spch_unx.out



Processing the installation verification files on the PC:
---------------------------------------------------------

1. Run the PC installation verification file ts_dos.bat by typing:
        ts_dos.bat

   The compare commands at the end of this file should yield no
   differences.

   Listing of file ts_dos.bat:
   ===========================

   coder spch_dos.inp spchtst.cod
   ed_iface spchtst.cod spchtst.dec
   decoder spchtst.dec spchtst.out

   fc /b spchtst.cod spch_dos.cod
   fc /b spchtst.dec spch_dos.dec
   fc /b spchtst.out spch_dos.out

More file format information:
-----------------------------

The file format of the supplied binary data (*.inp, *.cod, *.dec, and
*.out) and the resulting speech encoded parameter data is 16-bit binary
data which is read and written in 16 bit words.  The data is therefore
platform DEPENDENT.  This is advantageous since no data conditioning
is required to run files already present on the target platform.

The files contain only data, i.e., there is no header.
