This is the README file that explains a lot of things on the simulators & company.

=======================================================

gbDVB v. 3.4 - An ETSI DVB standard set
of (de)coders/(de)modulators

Copyright (C) 2000-2009 by Giuseppe Baruffa

=======================================================

Contents
________

1.  General information
2.  Current version
3.  Build from source
4.  Command line options
5.  Output file formats
6.  Performance
7.  Revision history
8.  Auxiliary programs & files
9.  Todo list
10. Licensing information
11. Credits & websites

1. General information
______________________

The aim of this project is to offer to the interested enthusiast (!?) the possibility to simulate the information flow of a DVB system. As you know, DVB is an European consortium that has implemented a digital television broadcasting standard.
The target programs of this project pick up an MPEG-2 encoded transport stream in order to drop down a digital baseband signal that is compliant with the DVB standards.
All in simple and pure C.

With the addition of standard input and output management, now it is easy to pipe encoders and decoders for simulation purposes. Even a TCP/IP link may be used to send data from a client to a server, thus improving the simulation speed.

From version 3.4 onwards, it is required that you register the software at

http://dsplab.diei.unipg.it/software/gbdvb/register

After registering, you will receive an unlocking key via email that will allow you to remove the initial delay at the beginning of every simulation. The registration is FREE, you will never be asked money or similar goods, I have done this only to collect some statistics on the typical usage of these programs.

Currently implemented programs are:

DVBTENCO - This terrestrial encoder/modulator follows the specifications of
the standard ETSI EN 300 744 V1.5.1 (2004-11).
DVBTDECO - A demodulator/decoder for dvbtenco.
DVBSENCO - This satellite encoder/modulator follows the specifications of
the standard ETSI EN 300 421 V1.1.2 (1997-08).
DVBSDECO - A demodulator/decoder for dvbsenco.
MPEG2GEN - Random MPEG-2 TS generator
GSEGEN   - Random GSE generator
T1000    - A graphical front-end for the programs above.

The author is Giuseppe Baruffa (baruffa@diei.unipg.it), currently assistant professor at the Department of Electronic and Information Engineering of the University of Perugia, Italy. For further information about the author, you can visit his homepage

http://dante.diei.unipg.it/~baruffa

or

http://dsplab.diei.unipg.it

Copyright (C) 2000-2009 by Giuseppe Baruffa

2. Current version
__________________

Current versions of the DVB compliant software is

Dvbtenco v. 3.0b - (2008/10/24)
Dvbtdeco v. 0.3b - (2009/02/02)
Dvbsenco v. 0.3b - (2007/12/11)
Dvbsdeco v. 0.3b - (2007/12/11)

http://dante.diei.unipg.it/dvbt
http://dsplab.diei.unipg.it/software/gbdvb

Supported platforms are:

* Windows
* Linux
* BSD

Whenever a new version is released, the Win/Lin/BSD binaries will be made available. Other platforms' executables once used to exist (namely Solaris on Sparc and on x86, as well as QNX on x86). The programs do not currently adopt multithreading, thus there is no apparent advantage when they are run on a multiprocessor/multithreaded architecture.

3. Build from source
____________________

Source files are not available for free to the public; this section is a reminder for those who get involved in source preparation and building. There are different ways to build the exes, depending on the CPU and OS.
The following methods are provided, in order of support:

* Makefile: open the Makefile, uncomment the section related to the CPU
architecture you are on, and type make/gmake (gcc for Linux/BSD) or
nmake (VC++ 6 for Windows).
* Workspace: open the .dsw VC++ 6 workspace, activate the "all" project and build
it (Windows); open the Code::Blocks .workspace and build all under Linux.
* Solution: open the .sln VS 2003 solution and build the projects.
* Documentation: run doxygen on the provided Doxyfile.

4. Command line options
_______________________

4.1 Common options
******************
Since all the programs are in the same family or standard class, a number of command line options are shared among them. These are:

-i      MPEG-2 transport stream file name or standard input

This is the name of a file containing the transport stream to deliver
to the 'broadcastees'. Essentially, it is a sequence of 188-byte long
packets, the first byte (of each packet) being a SYNC byte with a value
of 0x47. This is the only requirement on the input stream.
You can use "stdin" as file name, in order to get via piping the data
from standard input.

-o      Output base file name, standard output, or network destination

This is the base name of the output files. The extension (after the .)
is maintained as it is, while different prefixes are attached to the
part before the extension in order to identify the relevant outputs.
See the section on output files for the extensions and the format.
You can use "stdout" as file name, in order to send data via piping
to the standard output (basic time dump data are sent).
You can use the URI "gb://address:port" to send the time stream via
TCP/IP to a remote server listening at a certain port

-l      log file name

The name of a file containing the transcript of the command line
output. By default, it is "test.log".

-m      OFDM mode {2k | 4k | 8k}

Either 2048, 4096, or 8192 carriers are available.

-M      constellation order {4 | 16 | 64}

The encoded bits are mapped on the carriers via 4-QAM (QPSK),
16-QAM or 64-QAM (2, 4, or 6 bits per symbol, respectively).

-a      Hierarchy and uniformity order {NH | 1 | 2 | 4}

The (de)modulator can operate in hyerarchical mode, where two
independent MPEG-2 streams are encoded. The resulting constellations are
characterized by a parameter \alpha that denotes the ruggedness of the
high-priority stream with respect to channel (and other) impairments.
The higher this value, the safer is the transmission.

-D      Circular prefix duration {1/32 | 1/16 | 1/8 | 1/4}

OFDM can operate very well under severe multipath conditions, like
those encountered in Single Frequency Networks, where several
transmitters cover a wide area broadcasting in the same frequency
a GPS time-synchronized signal. The larger is the space separation
among transmitters or the multipath delay spread, the longer prefix
duration is required. Keep in count at least 3 micros for every km.

-p      puncturing rate, NH {1/2 | 2/3 | 3/4 | 5/6 | 7/8}
-php    puncturing rate, HP {1/2 | 2/3 | 3/4 | 5/6 | 7/8}
-plp    puncturing rate, LP {1/2 | 2/3 | 3/4 | 5/6 | 7/8}

The inner encoder produces a highly protected data stream, at the
expense of useful bit rate. You can trade off protection with bit rate
by raising the puncturing rate from 1/2 up to 7/8.
Nonhyerarchical OR (High Priority AND Low Priority) rates allowed.

-idi    In-depth interleaving, only for 2k and 4k modes

In 2k and 4k modes only, the 8k symbol interleaver can be used,
providing for a larger interleaving depth.

-c      convolutional interleaver initialization {0 | rand}

When the convolutional interleaver begins to operate, its registers are
usually empty. However, this may cause unmodulated carriers in the OFDM
signal, with large spikes appearing at the beginning of the post-IFFT
stream. With this option, the registers can be filled by random data,
thus avoiding range problems in the digitized stream.
The same behavior applies to NH OR (HP AND LP) streams.

-f      frequency mapping method {0 | BBIF | INV}

Data, pilot and TPS carriers can be mapped to the frequency domain in
two different modes. If the centre carrier is mapped to the zero
frequency, then you may directly use the time domain dump for generating
an IF signal at the desired IF. On the contrary, if the centre carrier
is mapped to the centre frequency, you obtain a BB signal that is
already near zero-IF modulated. Last, some demod chips expect an
inverted spectrum, due to the heterodyning process. This is exactly like
the zero IF method, only that the highest carrier number is mapped to
the lowest frequency, and vice versa.

-F      signal generator format {std | agi | agiold}**

This switch must be used together with the '-d t' option; you may
create binary files ready for pick-up by digital waveform generators.
If you do not specify a format, the standard one will be used.
Currently supported formats are:

standard - IEEE 32 bit floating point precision complex DVB-T signal.
See below for its format.
agi - Agilent ESG new format: one file, I and Q alternating, 16 bit per
sample, signed.
agiold - Agilent ESG-D with Option UND signal generators format: two
files (I and Q), 14 bit per sample, Marker 1 and Marker 2 bits set
to zero, unsigned.
!!NOTE!!: this is an old format. Use the new 'agi' format, instead.

-g      gain factor {real number}

When converting from the high-precision, 32 bit floating point internal
format to a fixed point format, the OFDM signal is unavoidably clipped,
since it basically resembles a gaussian signal with a large dynamic
range. Truncating the tails of the gaussian is a 'noisy' operation.
The larger is the gain factor, the lesser are the tails truncated, the
larger is the quantization noise. Just leave this field blank to use the
default internal optimum value, or specify a value in the range from 3.0
to 5.0 (4.0-4.2 is a good starting point).

-s      base size of internal buffers {integer number between 5 and 1000}

Change the internal sizes of simulation buffers, based on the size
used by MPEG-2 file reading subroutine: it will read this number of
packets at a time, roughly, and will try to process them.

-v      verbosity level {0 | 1 | 2 | 3 | 4}

You can receive more or less information from the encoder by selecting
different levels of verbosity. Verbosity equal to zero means no output.

-V      version number

Print version number and exit.

-R      Register

Use this switch to enter the registration data that you have received
via e-mail.

The program will connect to the internet and look for updates.

4.2 DVBTENCO
************
Dvbtenco is a statically linked command-line executable that reads an MPEG-2 Transport Stream file and drops a binary file containing the output baseband digital signal. Moreover, options provide for dropping intermediate binary files, i.e. digital streams caught along the encoding path, such as, for example, the block encoded stream, the punctured stream, and the pre-IFFT (frequency domain) sequence.
Currently available options are:

-i      MPEG-2 NH transport stream file name
-ihp    MPEG-2 HP transport stream file name
-ilp    MPEG-2 LP transport stream file name

Nonhyerarchical OR (High Priority AND Low Priority) streams allowed.

-o      Output base file name

-l      log file name

-m      OFDM mode {2k | 4k | 8k} (-- CHANGED --)

-M      constellation order {4 | 16 | 64}

-a      Hyerarchy and uniformity order {NH | 1 | 2 | 4}

-D      circular prefix duration {1/32 | 1/16 | 1/8 | 1/4}

-p      puncturing rate, NH {1/2 | 2/3 | 3/4 | 5/6 | 7/8}
-php    puncturing rate, HP {1/2 | 2/3 | 3/4 | 5/6 | 7/8}
-plp    puncturing rate, LP {1/2 | 2/3 | 3/4 | 5/6 | 7/8}

-idi    In-depth interleaving, only for 2k and 4k modes

-b      channel spacing {5 | 6 | 7 | 8}

DVB-T is envisaged to operate both in VHF and UHF channels, as well as
in a pseudo-NTSC channelization. Thus, channel bandwidth (in MHz) may
vary accordingly.

-cid    cell identification {integer number between 0 and 65535}

These 16 bits are used to identify the cell which the signal comes from.
It is the cell_id declared in the System Information DVB specifications.

-c      convolutional interleaver initialization {0 | rand}

-f      frequency mapping method {0 | BBIF | INV}

-I      interpolation rate {1x | 2x | 4x}**

The time waveform can be converted from the standard 1x rate to an
interpolated one. A polyphase filter is used to attenuate the images
down to 60 dB below the main component (zero IF signal only). The
signal is delayed by 15/2 and 31/4 lags from the 1x signal for the 2x
and 4x streams, respectively.

-F      signal generator format {std | agi | agiold}**

-g      gain factor {real number}

-d      dump level {ercvpbsmft}

The encoder may dump signals taken along the processing stages, at
different levels. You can select them by following the -d switch with
the parameters (after a space):

e - Energy disperser
r - Reed-Solomon encoder
c - Convolutional interleaver
v - Convolutional encoder
p - Puncturer
b - Bit interleaver
s - Symbol interleaver
m - Mapper
f - Pre-IFFT
t - Post-IFFT

Look at the section on file outputs for the formats implied.

-s      base size of internal buffers {integer number between 5 and 1000}

-v      verbosity level {0 | 1 | 2 | 3 | 4}

-V      version number

(**) When operated this way, the simulator may run significantly slower than
usual. Moreover, the output file size may be larger than expected: be careful!
See the section on file outputs for the format.

4.3 DVBTDECO
************
Dvbtdeco is a statically linked command-line executable that reads a binary file containing the input baseband digital signal and produces an MPEG-2 Transport Stream file as output. Moreover, options provide for dropping intermediate binary files, i.e. digital streams caught along the encoding path, such as, for example, the block decoded stream, the depunctured stream, and the post-FFT (frequency domain) sequence.
Since this is a very basic version, the program will work iff

* the input baseband signal is properly synchronized, i.e. it has
not suffered a delay with respect to the original, transmitted signal.
In case there is such delay, you should correct it properly.
* the input baseband signal is in standard format (std).
* you specify exactly all the modulation/encoding parameters expected in the
received signal: there is no auto-detection mode at this stage of
development.

Currently available options are:

-i      ADC input file name, standard input, or network source

This binary file must contain a DVB-T signal saved in the same format
used by the modulator as output file (standard format).
You can use "stdin" as file name, in order to get via piping the data
from standard input.
You can use the URI "gb://address:port" to get the time stream via
TCP/IP from any remote client sending to a certain port.

-o      Base output file name and extension

This is the base name of the output files. The extension (after the .)
is maintained as it is, while different prefixes are attached to the
part before the extension in order to identify the relevant outputs.
See the section on output files for the extensions and the format.
You can use "stdout" as file name, in order to send data via piping
to the standard output (basic time dump data are sent).

-l      log file name

-m      OFDM mode {2k | 4k | 8k}

-M      constellation order {4 | 16 | 64}

-a      Hyerarchy and uniformity order {NH | 1 | 2 | 4}

-D      circular prefix duration {1/32 | 1/16 | 1/8 | 1/4}

-p      puncturing rate, NH {1/2 | 2/3 | 3/4 | 5/6 | 7/8}
-php    puncturing rate, HP {1/2 | 2/3 | 3/4 | 5/6 | 7/8}
-plp    puncturing rate, LP {1/2 | 2/3 | 3/4 | 5/6 | 7/8}

-idi    In-depth interleaving, only for 2k and 4k modes

-b      channel spacing {5 | 6 | 7 | 8}

DVB-T is envisaged to operate both in VHF and UHF channels, as well as
in a pseudo-NTSC channelization. Thus, channel bandwidth (in MHz) may
vary accordingly.

-cid    cell identification {integer number between 0 and 65535}

These 16 bits are used to identify the cell which the signal comes from.
It is the cell_id declared in the System Information DVB specifications.

-c      convolutional interleaver initialization {0 | rand}

-f      frequency mapping method {0 | BBIF | INV}

-I      interpolation rate {1x | 2x | 4x}**

The time waveform can be converted from the standard 1x rate to an
interpolated one. A polyphase filter is used to attenuate the images
down to 60 dB below the main component (zero IF signal only). The
signal is delayed by 15/2 and 31/4 lags from the 1x signal for the 2x
and 4x streams, respectively.

-F      signal generator format {std | agi | agiold}**

-g      gain factor {real number}

-d      dump level {ercvpbsmft}

The encoder may dump signals taken along the processing stages, at
different levels. You can select them by following the -d switch with
the parameters (after a space):

e - Energy disperser
r - Reed-Solomon encoder
c - Convolutional interleaver
v - Convolutional encoder
p - Puncturer
b - Bit interleaver
s - Symbol interleaver
m - Mapper
h - Estimated channel
q - Equalized mapper
f - Pre-IFFT
2 - MPEG-2 TS

Look at the section on file outputs for the formats implied.

-s      base size of internal buffers {integer number between 5 and 1000}

-v      verbosity level {0 | 1 | 2 | 3 | 4}

-V      version number

(**) When operated this way, the simulator may run significantly slower than
usual. Moreover, the output file size may be larger than expected: be careful!
See the section on file outputs for the format.

4.4 DVBSENCO
************
Dvbsenco is a statically linked command-line executable that reads an MPEG-2 Transport Stream file and drops a binary file containing the output baseband digital signal. Moreover, options provide for dropping intermediate binary files, i.e. digital streams caught along the encoding path, such as, for example, the block encoded stream, the punctured stream, and the time domain sequence.
Currently available options are:

-i      MPEG-2 transport stream file name or standard input

-o      Output base file name, standard output, or network destination

-l      Log file name

-p      puncturing rate {1/2 | 2/3 | 3/4 | 5/6 | 7/8}

The inner encoder produces a highly protected data stream, at the
expense of useful bit rate. You can trade off protection with bit rate
by raising the puncturing rate from 1/2 up to 7/8.

-b      3-dB bandwidth {36.0000 MHz}

This parameter is used to set the output sampling rate and,
consequently, the data throughput. The relationship between 3-dB
bandwidth and sampling rate is BW/Rs=1.28, as exemplified in Annex C
of EN 300 421.

-c      convolutional interleaver initialization {0 | rand}

-v      Verbosity level {0 | 1 | 2 | 3 | 4}

-V      Print version number and exit

-d      dump level {ercvpmtx}

The encoder may dump signals taken along the processing stages, at
different levels. You can select them by following the -d switch with
the parameters (after a space):

e - Energy dispersed bytes
r - Reed-Solomon encoded bytes
c - Convolutionally interleaved bytes
v - Convolutionally encoded bits
p - Punctured bits
m - Mapped symbols
t - Time interpolated samples
x - Time output in -F format

Look at the section on file outputs for the formats implied.

-I      interpolation rate {2 | 4 | 8}

The time waveform is converted from the standard 1x rate to an
interpolated one. A root raised cosine filter is used to attenuate
the images and shape the TX signal.

-F      signal generator format {std | agi | agiold}

-g      gain factor {real number}

-s      Internal buffer base size {integer number between 5 and 1000}

4.5 DVBSDECO
************
Dvbsdeco is a statically linked command-line executable that reads a binary file containing the input baseband digital signal and produces an MPEG-2 Transport Stream file as output. Moreover, options provide for dropping intermediate binary files, i.e. digital streams caught along the decoding path.
The dumps should be synchronized, i.e. the bits/bytes positions correspond to those observed in the modulator output dumps. Thus, for example, the deinterleaver and Viterbi decoder dumps are stripped of leading invalid data. Since this is a very basic version, the program will work iff

* the input baseband signal is properly synchronized, i.e. it has
not suffered a delay with respect to the original, transmitted signal.
In case there is such delay, you should correct it properly.
* the input baseband signal is in standard format (std).
* you specify exactly all the modulation/encoding parameters expected in the
received signal: there is no auto-detection mode at this stage of
development.

Available command line options are:

-i      ADC input file name, standard input, or network source

This binary file must contain a DVB-S signal saved in the same format
used by the modulator as output file (standard format)
You can use "stdin" as file name, in order to get via piping the data
from standard input.
You can use the URI "gb://address:port" to get the time stream via
TCP/IP from any remote client sending to a certain port.

-o      Base output file name and extension

This is the base name of the output files. The extension (after the .)
is maintained as it is, while different prefixes are attached to the
part before the extension in order to identify the relevant outputs.
See the section on output files for the extensions and the format.
You can use "stdout" as file name, in order to send data via piping
to the standard output (basic time dump data are sent).

-l      Log file name

-p      puncturing rate {1/2 | 2/3 | 3/4 | 5/6 | 7/8}

-vit    Viterbi decoding type {hard | soft}

Inner channel decoding is performed via the Viterbi algorithm, using
either hard or soft metric. A 2-dB gain is expected by using soft.

-b      3-dB bandwidth {36.0000 MHz}

-c      convolutional interleaver initialization {0 | rand}

-v      Verbosity level {0 | 1 | 2 | 3 | 4}

-V      Print version number and exit

-d      dump level {mpvcre2}

The decoder may dump signals taken along the processing stages, at
different levels. You can select them by following the -d switch with
the parameters (after a space):

m - Mapped symbols
p - Punctured bits
v - Convolutionally encoded bits
c - Convolutionally interleaved bytes
r - Reed-Solomon encoded bytes
e - Energy dispersed bytes
2 - MPEG-2 transport stream bytes

Look at the section on file outputs for the formats implied.

-I      interpolation rate {2 | 4 | 8}

-F      signal generator format {std | agi | agiold}

-m		Enable measurement mode

This switch expects that a stream of MPEG-2 NULL packets is received
and computes the corresponding Symbol and Bit error Rate

-g      gain factor {real number}

-s      Internal buffer base size {integer number between 5 and 1000}

5. Examples
______________________

Piping:

mpeg2gen -z 100000000 -t null -o stdout |
dvbsenco -i stdin -o stdout |
dvbsdeco -i stdin -m

Network:

dvbsdeco -i gb://localhost:10200 -m

mpeg2gen -z 50000 -t null -o stdout |
dvbsenco -i stdin -o gb://localhost:10200

6. File formats
______________________

The programs may dump signal streams from several "taps" along the encoding and modulation stages. Generally, the files are organized as a serial dump of the data, with no peculiar header among consecutive blocks of processed bits, bytes, symbols or samples. For an explicative way to read and import data dumps, please refer to the Matlab script (mega_test.m) that comes with this software.  Dump files can be read according to the following specifications; a prototype C fread() call is given as an example:

* MPEG-2 TS dump: files *.m2v, *_hp.m2v, *_lp.m2v
(unsigned char); bit ordering is (MSB ... ... LSB)
Each byte carries ... a byte!
"fread((unsigned char *), sizeof (unsigned char), int, FILE *);"

* Energy dispersal dump: files *_ed.bin, *_edhp.bin, *_edlp.bin
(unsigned char); bit ordering is (MSB ... ... LSB)
Each byte carries ... a byte! SYNC1 byte inversion is included.
"fread((unsigned char *), sizeof (unsigned char), int, FILE *);"

* Reed-Solomon dump: files *_rs.bin, *_rshp.bin, *_rslp.bin
(unsigned char); bit ordering is (MSB ... ... LSB).
Each byte carries a codebyte in GF(2^8).
"fread((unsigned char *), sizeof (unsigned char), int, FILE *)"

* Convolutional interleaver dump: files *_ci.bin, *_cihp.bin, *_cilp.bin
(unsigned char); bit ordering is (MSB ... ... LSB).
Each byte carries 8 bits.
"fread((unsigned char *), sizeof (unsigned char), int, FILE *)"

* Convolutional encoder dump: files *_ve.bin, *_vehp.bin, *_velp.bin
(unsigned char); bit ordering is (MSB ... ... LSB).
Each byte carries a bit --> ( 0  0  0  0  0  0  0  b).
"fread((unsigned char *), sizeof (unsigned char), int, FILE *)"
N.B.: only for the decoders, the format is slightly different
in that the byte value 0 stands for a strong '0' whereas the byte
value 255 stands for a strong '1'

* Puncturer dump: files *_pu.bin, *_puhp.bin, *_pulp.bin
(unsigned char); bit ordering is (MSB ... ... LSB).
Each byte carries a bit --> ( 0  0  0  0  0  0  0  b).
"fread((unsigned char *), sizeof (unsigned char), int, FILE *)"
N.B.: only for the decoders, the format is slightly different
in that the byte value 0 stands for a strong '0' whereas the byte
value 255 stands for a strong '1'

* Bit interleaver dump: files *_bi.bin
(unsigned char); bit ordering is (MSB ... ... LSB).
4-QAM  --> ( 0  0  0  0  0  0 I0 I1)
16-QAM --> ( 0  0  0  0 I0 I1 I2 I3)
64-QAM --> ( 0  0 I0 I1 I2 I3 I4 I5).
"fread((unsigned char *), sizeof (unsigned char), int, FILE *)"

* Symbol interleaver dump: files *_si.bin
(unsigned char); bit ordering is (MSB ... ... LSB)
4-QAM  --> ( 0  0  0  0  0  0 y0 y1)
16-QAM --> ( 0  0  0  0 y0 y1 y2 y3)
64-QAM --> ( 0  0 y0 y1 y2 y3 y4 y5).
"fread((unsigned char *), sizeof (unsigned char), int, FILE *)"

* Mapper dump: files *_ma.bin
complex;
There are 8 bytes for each output sample, 4 for the real part and 4
for the imaginary part, in floating point single precision format.
"fread((complex *), sizeof (complex), int, FILE *)"

* Pre-IFFT dump: files *_fd.bin
complex;
There are 8 bytes for each output sample, 4 for the real part and 4
for the imaginary part, in floating point single precision format.
The stream is dumped without guard band zeroes: only data.
"fread((complex *), sizeof (complex), int, FILE *)"

* Channel dump: files *_ch.bin
complex;
There are 8 bytes for each output sample, 4 for the real part and 4
for the imaginary part, in floating point single precision format.
The stream is dumped without guard band zeroes: only data.
"fread((complex *), sizeof (complex), int, FILE *)"

* Equalized dump: files *_eq.bin
complex;
There are 8 bytes for each output sample, 4 for the real part and 4
for the imaginary part, in floating point single precision format.
The stream is dumped without guard band zeroes: only data.
"fread((complex *), sizeof (complex), int, FILE *)"

* Post-IFFT or interpolated time (standard) dump: files *.bin
complex;
There are 8 bytes for each output sample, 4 for the real part and 4
for the imaginary part, in floating point single precision format.
"fread((complex *), sizeof (complex), int, FILE *)"

* Post-IFFT or interpolated time (agi) dump: files *_agi.bin
icomplex;
bit ordering is (MSB ... ... LSB).
There are 4 bytes for each output sample, 2 for the real part and 2
for the imaginary part, in fixed point format.
"fread((icomplex *), sizeof (icomplex), int, FILE *)"

* Post-IFFT or interpolated time (agiold) dump: files *_I.bin, *_Q.bin
uint16;
bit ordering is (MSB ... ... LSB).
There are two bytes for each 14 bit output sample (the two MSBs
representing Marker 1 and Marker 2 are zeroed).
"fread((uint16 *), sizeof (uint16), int, FILE *)"

The types are defined as

typedef struct {float re, im;} complex;
typedef struct {signed short int re, im;} icomplex;
typedef (unsigned short int) uint16;

WARNING: Although the programs are capable of managing large files (i.e. files with a size larger than 2 GB), the file system you are running it on may be not! For example, FAT16 has a 2 GB limit and FAT32 has a 2/4 GB limit, whereas NTFS, UFS, EXT*FS and other ones do not (virtually) suffer from this.

7. Performance
______________

Some performance reports about the terrestrial simulator, dvbtenco.

7.1 OFDM Modulator
******************
When compared to a Matlab implementation in double precision, the signal to quantization noise ratio of the simulator output gets 63 dB in 2k mode and 34 dB in 8k mode. Possibly, this last one can be improved.

7.2 Required memory
*******************
The program itself gives clues about RAM occupancy, just after the operational parameters summary. It is just an estimation, and the real occupancy may reach 10-15 MB.

7.3 Simulation speed
********************
A simple speed test can be run on the supported platforms (use test_dvbt.bat for Windows and test_dvbt.sh for Unix). The relevant output can be processed in order to obtain clues on the performance. You find, in the following, some results: if you can supply me with different ones, please drop a mail.
Test parameters: a 1,200,000 bytes long MPEG-2 TS is used as input to the program. A FOR control loop executes dvbtenco with all the possible parameters combination: 2 modes, 3 constellations, 4 cyclic prefixes, and 5 puncturing rates.
The verbosity set to 1 gives just the speed; the output is filtered (wppcheck) and the minimum, maximum and average speed are reported.
In order to consider different CPU clock frequencies, a Weighted Performance Parameter (WPP) is used to compare OS and architectures: it is simply defined by the ratio between the average speed (bps) and the real clock frequency (MHz). This is indeed a quite unfair comparison parameter, since it does not keep count of waiting times and cache size, that do not depend on CPU frequency.
N.B. : (*) tests performed with dvbtenco v. 1.2g - Beta
(§) tests performed with dvbtenco v. 1.2i - Beta
(°) tests performed with dvbtenco v. 2.1b
N.B.2: Windows platform compiled with VC++ 6.0, Linux, QNX and Solaris, Intel platforms compiled with GCC, Solaris Sparc platform compiled with Sparc Compiler Forte C++.

==============================================================================
|                        |               |    Comp. speed (kbps)    |        |
| CPU (brand and speed)  |      OS       |__________________________|   WPP  |
|                        |               |  Avg.  |  Min.  |  Max.  |        |
==============================================================================
|                        |               |        |        |        |        |
| Real time execution    | Any           | 16235  | 4976.5 |  31668 |  NULL  |
| requirements           |               |        |        |        |        |
------------------------------------------------------------------------------
|                        |               |        |        |        |        |
| Intel Pentium III (*)  | Windows XP    | 1841.1 |  822.7 | 2729.5 |  3507  |
| 525 MHz, 192 MB SDRAM  |---------------|--------|--------|--------|--------|
|                        | Linux 2.4     | 1826.9 |  786.4 | 2755.9 |  3480  |
|                        |---------------|--------|--------|--------|--------|
|                        | Solaris 2.8   | 1868.0 |  805.4 | 2810.4 |  3558  |
|                        |---------------|--------|--------|--------|--------|
|                        | QNX 6.2       | 1850.0 |  810.1 | 2768.6 |  3524  |
|                        |---------------|--------|--------|--------|--------|
|                        | Windows 98    | 1831.6 |  810.8 | 2748.3 |  3489  |
------------------------------------------------------------------------------
|                        |               |        |        |        |        |
| Sun UltraSPARC IIi (*) | Solaris 2.7   | 1612.5 |  681.0 | 2538.0 |  4031  |
| 400 MHz, 128 MB RAM    |               |        |        |        |        |
------------------------------------------------------------------------------
|                        |               |        |        |        |        |
| Sun UltraSPARC IIi (*) | Solaris 2.8   | 1816.0 |  624.3 | 2740.8 |  4127  |
| 440 MHz, 512 MB RAM    |               |        |        |        |        |
------------------------------------------------------------------------------
|                        |               |        |        |        |        |
| Intel Pentium 4 (*)    | Linux 2.4     | 6171.4 | 2842.6 | 8883.0 |  3429  |
| 1.8 GHz, 1024 MB RDRAM |               |        |        |        |        |
------------------------------------------------------------------------------
|                        |               |        |        |        |        |
| Intel Pentium 4 (*)    | Windows XP    | 7342.6 | 3704.4 |  10110 |  2914  |
| 2.4 GHz, 512 MB RDRAM  |               |        |        |        |        |
------------------------------------------------------------------------------
|                        |               |        |        |        |        |
| Intel Pentium 4 HT (§) | Windows XP    | 7824.9 | 3841.3 |  11166 |  2795  |
| 2.8 GHz, 512 MB DDRAM  |               |        |        |        |        |
------------------------------------------------------------------------------
|                        |               |        |        |        |        |
| Intel Pentium 4 HT (°) | Windows XP    | 7862.4 | 3578.9 |  12340 |  2808  |
| 2.8 GHz, 512 MB DDRAM  |               |        |        |        |        |
------------------------------------------------------------------------------
|                        |               |        |        |        |        |
| Intel Pentium 4 HT (*) | Linux 2.4     | 9233.4 | 4314.6 |  13265 |  3298  |
| 2.8 GHz, 512 MB DDRAM  |               |        |        |        |        |
------------------------------------------------------------------------------
|                        |               |        |        |        |        |
| AMD Dual Athlon XP2600 | Linux 2.4     | 7578.3 | 3476.5 |  11179 |  3499  |
| 2.1 GHz, 2 GB RAM (§)  |               |        |        |        |        |
------------------------------------------------------------------------------
|                        |               |        |        |        |        |
| SunFire 9800 24 sparc7 | Solaris 2.9   | 3461.3 | 1457.7 | 5589.3 |  3846  |
| 900 MHz, 192GB RAM (§) |               |        |        |        |        |
------------------------------------------------------------------------------
|                        |               |        |        |        |        |
| Intel Core 2 Duo x64   | Linux 2.6     | 14862  | 6060.2 | 21251  |  6261  |
| 2400 MHz, 2GB RAM      |               |        |        |        |        |
------------------------------------------------------------------------------

8. Revision history
___________________

(2009/06/05) - 3.4 is the first release with registration of account

(2009/02/06) - Released nearly fully functional T1000

(2008/10/24) - T1000 and gsegen
+ new version of T1000, based upon a library
+ first version of gsegen, used to generate GSE random streams
- dvbsdeco has been temporarily deleted

(2007/12/31) - dvbsenco 0.3b and dvbsdeco 0.1b
+ added use of standard input and output for piping
+ added use of TCP/IP for communicating data between a client
and a server

(2006/12/30) - dvbsenco, version 0.1b
+ first version of the satellite DVB-S modulator

(2006/08/03) - dvbtenco, version 2.1b
+ TPS bits 30, 31, and 32 now change accordingly with
the adopted coding rate, in nonhyerarchical mode
- dvbtdeco, version 0.2a
+ First, slow, and buggy release of the terrestrial decoder

(2005/08/15) - version 2.0b
+ Added 4k mode and 5 MHz bandwidth

(2005/08/15) - version 1.2l
+ Added the cell identification option

(2004/12/25) - version 1.2k
+ The 'beta' is gone!
+ Interpolation independent from the time dump format
+ Support for Agilent vector signal generators
+ Inverted frequency mapping

(2004/08/23) - Version 1.2j beta
+ Base band or Low IF frequency mapping
+ Base band interpolated output format

(2003/08/16) - Version 1.2i beta
+ Largefiles (>2GB) support under Solaris and Linux
+ Fixed a bug in 2/3 puncturing mode

(2003/04/25) - Version 1.2h beta
+ Ported the simulator to QNX 6.2 x86 platform
+ Refixed a bug in TPS&pilot insertion
+ BCH encoding of TPS carriers according to standard
+ Beta support for Agilent family of signal generators

(2002/12/01) - Version 1.2g beta
+ Fixed a bug in the cyclic prefix extension
+ Fixed a bug in TPS&pilot insertion
+ Added an Intellectual Property control: check for binary
executable unauthorized changes

(2002/10/07) - Version 1.2f beta
+ Fixed a bug in the dimensioning of simulation cycles, with an
increased efficiency of the simulation buffers

(2002/08/15) - Version 1.2e beta
+ Fixed a bug in the RS generator polynomial: first root is now
0x01
+ Fixed a bug in the RS output stream: the parity bytes are
calculated with data bytes in correct order
+ Added the possibility to choose the log file name
+ Added the possibility to choose how to fill convolutional
interleaver registers at initialization
+ Added the dump after SYNC1 byte inversion & energy dispersal

(2002/06/19) - Version 1.2d beta
+ Fixed a bug in the symbol interleaver address generation
scheme

(2002/05/26) - Version 1.2c beta
+ Fixed a bug in the scrambling/SYNC1 inversion routine

(2001/12/12) - Version 1.2b beta

(2000/08/28) - Version 0.1b beta
+ Very first buggy version

9. Auxiliary programs & files
_____________________________

With the simulator are bundled some auxiliary programs and files, used for the
tests before and after the run.

9.1 T1000
*********
T1000 is a Graphical User Interface (GUI) for the modulators/demodulators. As it is based on the same engine used by command line programs, it behaves exactly in the same way, yet provides flexibility and manageability to those that are more familiar with mice and clicks.

9.2 MPEG2GEN
************
Mpeg2gen is a simple MPEG-2 TS generator. Data are generated in an absolutely random way: they do not represent any real sequence.

Current available options are:

-o      Output file name (use "stdout" for stdout)
-z      Output file size (50000)
-t      Generator type {zero | null | rand | dvb}
zero - SYNC + ZEROS
null - ISO/IEC NULL packets
rand - SYNC + ANSI RAND() packets
dvb  - DVB reference packets
-s      Packets to generate at a time {100}
-V      Print version number and exit
-l      Log file name
-h      Display help info

9.3 GSEGEN
**********
Gsegen is a simple random Generic Encapsulated stream (GSE) generator. Data are generated in an absolutely random way: they do not represent any real sequence. It is used in DVB2 systems as replacement of the MPEG-2 TS.

Current available options are:

-o      Output file name (use "stdout" for stdout)
-z      Output file size (50000)
-t      Generator type
zero - ZEROS
rand - ANSI RAND()
-s      Packets to generate at a time {100}
-bmin   Minimum size of Base-Band Frame {4096}*
-bmax   Maximum size of Base-Band Frame {-1}*
-pmin   Minimum size of packet data units {512}*
-pmax   Maximum size of packet data units {-1}*
-V      Print version number and exit
-l      Log file name
-h      Display help info
* Specifying only the minimum value will produce fixed size packets, and -1 will let default values in

9.4 WPPCHECK
************
Wppcheck is a a Weighted Performance Parameter checker: it accepts the data produced by the batch tests. The usage is simple:

wppcheck file_name clock_mhz

- file_name is the result file produced by running the test scripts
- clock_mhz is the clock frequency expressed in MHz

9.5 OTHER FILES
***************
test.m2v
- A 50 KB long MPEG-2 TS test file

test_dvbte.bat
test_dvbte.sh
test_dvbse.bat
test_dvbse.sh
- Batch scripts used for the speed tests.

dvbte_test.m
dvbse_test.m
- Matlab script for plotting all the modulator data dumps in nice format.

dvbtd_test.m
- Matlab script for testing the transmitter-(channel+noise)-receiver chain and plotting all the results nicely.

dvbt_ber.m
- Matlab script for plotting the BER curve of the system at various levels of C/N and for different channels

dvbs_ber.m
- Matlab script for plotting the BER curve of the system at various levels of C/N

N.B.: Matlab tests are prepared with version 5.3; ver. 6.5 may fail if some function syntax is not modified.

10. Todo list
____________

- Macintosh version
- dvbs2enco, dvbcenco, etc.

11. Licensing information
________________________

These programs are freely distributed in the hope that they will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
It is forbidden to modify, patch, back-engineer, decompile, hack, crack the binary version of the programs (for any available platform).
It is forbidden to redistribute to anyone the binary version of the programs (for any available platform): the only authorized download is from the site

http://dante.diei.unipg.it/dvbt

The binary version of these programs can be freely downloaded and used for educational and research purposes by public or private academic institutions.
The use of these programs for educational and research purposes by private industries, research laboratories and, in general, profit organizations is authorized and encouraged as well.
Whoever finds this little program helpful for his/her research or work, can drop me a mail (baruffa@diei.unipg.it) with a brief description of the project where the simulators have been used in, and I will put this on the website and in the Readme file. I will not ask you for money!

12. Credits & websites
_____________________

I wish to tank several people or/and their code for their contribution to this project.
First of all, Phil Karn's channel encoding/decoding routines, that helped me a lot for a fast implementation of the program.
Then, part of the code for OFDM modulator was derived from Don Cross's fft routines.
Grateful thanks go to Uli Marxmeier for his precise verification of the program capabilities and for the many discovered bugs.
I wish to acknowledge the work & hints of Luis del Pino and SeongWan Park for their help in correcting the RS encoding routine.
Many thanks to Philippe Duc, for his suggestions about the convolutional encoding correctness in the super-frame structure.
Karsten Schmidt (http://mikro.e-technik.uni-ulm.de/persons/schmidt/dvbt) has helped a lot in verifying and discovering bugs. He also reports that this program has helped in generating a DAC stream that was successfully received by a commercial DVB-T set top box. Karsten supplied the speed test for the SunFire 9800 and the Dual Athlon XP2600.
Thomas Pinz (FH-Regensburg, Germany) set up a test bench for this program, during its work for some tests of real DVB-T mobile receivers. He verified that the program runs correctly and the waveform is received and correctly decoded.
Hung-Jen Chang (Agilent, Taiwan) has prepared a similar setup. The waveform is received and correctly decoded. The transport stream is decoded as well. For more details and a overview of the setup, refer to the project home page.
Bugs on TPS in version 2.0 were discovered and signalled by Xitaoye and Alejandro Moya Molina.
Thanks to the courtesy of Paolo Monzoni of Agilent Italy, I had the chance to test the operation of the software encoder. I did this using an ESG 4438C Vector Signal Generator from Agilent and a Terratec Cynergy USB DVB-T decoder.
In May 2009 dvbtenco files have been succesfully tested with Aeroflex 3025C and 3035C vector signal generators and digitizers, thanks to the courtesy of Tim Carey of Aeroflex UK and Gianfelice Aricò of MPGInstruments Italy.

12.1 Information related to the platforms
*****************************************
http://www.microsoft.com ==> Bill Gates's Windows
http://www.sun.com       ==> Scott McNealy's SYSV OS
http://www.mandriva.com  ==> A top Linux distribution
http://www.qnx.com       ==> A very nice and fast *NIX realtime OS
http://www.wxwidgets.org ==> A portable, windowed GUI

12.2 Information related to the DVB standard
********************************************