howto.tex

This a framework to test new ideas in transmission technology. Actual development is a LDPC-coder in

shell2:SRadio/Radios/Simple/MS\$ make debug
shell3:SRadio/Radios/Simple\$ make show
\end{lyxcode}

This starts the server and the BS, then starts the MS. The third line starts
the visualize-tool, if you wish to do so. If an error is encountered, gdb will
stop in one of the two windows, and you can use the commands described above to
see what is wrong.


\subsection{Using ddd}

For better debugging, for example if your module doesn't crash, but
doesn't do what you expect it to do, you can use \emph{ddd}. To start
it, you go to the same directory where usually you type \emph{make
user} and type \emph{make ddd}. After this, you have to type \emph{break
main.c:36} and press F3 to start the program. Once it stops on the
breakpoint, all necessary libraries have been loaded and also the
modules you want to debug (given that you didn't make any errors in
setting up the \emph{Makefile}).

Now you can enter the name of a function to debug on top in the white
box and press on \emph{lookup} to the right of the box. Clicking with
the right mouse-button on a line you can set a breakpoint. Repeat
this procedure as often as necessary, then click on \emph{cont} and
watch what happens. \emph{next}, \emph{step}, right-clicking on variables
are other nice options to take. Try it, break it. Debugging is an
art!


\subsubsection{Known bugs}

DO NOT type \emph{run} in the command-line of ddd. This runs the program
without any command-line options that have been carefully crafted
to work with ddd. Do use the run-button or the menu \emph{Program-\textgreater{}Run
Again}. Optionally you can use the F3-key.


\chapter{Getting Started}

In this chapter you'll learn how to set-up your computer so as to
be able to run the MSR in simulation mode. If you want to work with
the MSR, you should read this chapter. First you have to make sure
that all necessary software is installed on your system, then you
have to download the necessary package, compile it, and finally you
can run the example.


\section{Prerequisites}

The MSR runs without problems on a linux-system. For the simulation-part,
an installation of the RTLinux is not necessary. The MSR relies on
some new packages, like a new linker and a QT-package. These should
be available with RH7.3 and newer, Mandrake 8.2 and newer as well
as Debian 3/testing and newer. The most common missing programs are:

\begin{lyxlist}{00.00.0000}
\item [linker]check with \emph{ld --version} whether it is something newer
or equal than 12.13.90 
\item [qt]check with \emph{qmake --version} and see if the version of QT
is bigger or equal than 3.0 
\item [libqwt]is used to display the graphics on screen. If you don't have
it installed, ask your system-administrator to install it. Alternatively
you can also install it in your home-directory. 
\end{lyxlist}
If one of these is missing, please contact your system administrator
or install the missing packages.


\section{Installing the MSR}

It is possible to use the MSR without the proper RF-hardware. For
this you will use a channel-simulation. In this section you learn
how to download and compile the MSR.


\subsection{Download the software}

From \emph{http://lcmpc10.epfl.ch/Menu/Download} you can download
the latest version of the MSR, which has a name like msr-{*}.tgz Once
it is on your computer, you can place it in a convenient directory
and untar it using \emph{tar xzf msr-{*}tgz} This will create a directory
named \emph{Main} and a lots of subdirectories and files in there.
Generally you will find README files in most of the directories. They
are useful if you need to know what goes on in this special place.
Do not hesitate to read them.


\subsection{Compile the software}

The software consists of two parts: the graphic display and the signal-processing
modules. For the graphical part, you have to change into \emph{Main/Tools/Visualize}
and run \emph{qmake visualize.pro} followed by a \emph{make}. If everything
goes well, you should have an executable called visualize.

After this you can change in the \emph{Main} directory and run \emph{make}
there. Supposing that everything goes well, you're ready to run the
examples.


\subsection{Common errors}


\subsubsection{While compiling 'Visualize' I get 'libqwt not found'}

Make sure that libqwt is installed and check eventually the path in
visualize.pro.


\section{Running the examples}

There are a couple of pre-defined radios in the subdirectory \emph{Radios/}.
The most simple is in \emph{Radios/Simple/}. Using the following commands,
you can display both the BS and the MS of this simple example:

\begin{lyxcode}
cd~Radios/Simple

make~server

make~show\_bsms~
\end{lyxcode}
If the installation of the MSR has been carried out successfully,
you should see now two windows popping up, showing the basestation
that emits the synchronisation-signal, as well as the mobile-station
that listens to this signal.

You can also run the other examples that you find in this directory,
namely \emph{Multiuser} and \emph{LDPC} just to get an idea what the
software-radio is all about. And remember: the same c-code also runs
in real-time on RF-hardware!


\chapter{Testing}

Once a new module has been written, or if something new should be
tried, a new testing-module should be written. A testing-module usually
consists of a simple chain with some output that tells the user whether
the test has succeeded or not. It is the first step towards writing
a Radio and using a new or modified module in real-time.


\section{\label{sub:Files}Files}

If you want to start a new test, create a new directory under \emph{Test/}
and add the name to the line

\begin{lyxcode}
DIRS~=~FirstChain~Memory~...~
\end{lyxcode}
of the file \emph{Test/Makefile}. Like this your test will be automatically
built when using \emph{make whole}. Next \emph{cd} in your new directory
and copy some files:

\begin{lyxcode}
cp~../../Conventions/test\_template.c~\textbackslash{}

~~~../../Conventions/Makefile.module~.~
\end{lyxcode}
The \emph{test\_template.c} should be renamed to something fitting
the pattern \emph{test\_{*}.c}, and this name should be appended to
the line

\begin{lyxcode}
MODULE\_NAME~=~
\end{lyxcode}
of the \emph{Makefile} (which has been renamed from \emph{Makefile.module}).
Now you are ready to modify your \emph{test\_{*}.c} file and test
it out, using

\begin{lyxcode}
make

make~user~
\end{lyxcode}
You can also have a look into different files that you find in the
directory \emph{Testing/{*}} to see different techniques on how to
do strange things.


\section{\label{sub:Main}Main}

The main-part of the module is in the function \emph{start\_it}. It
is called once when the module is loaded. For a small testing-module
you want to make perhaps only a small chain, something like

\begin{lyxcode}
swr\_chain\_create(~NEW\_SPC\_VAR(~''random'',~rnd~),

~~~~~~~~~~~~~~~~~~NEW\_SPC(~''modulator''~),

~~~~~~~~~~~~~~~~~~NEW\_SPC(~''demodulator''~),

~~~~~~~~~~~~~~~~~~NEW\_SPC\_VAR(~''sink'',~sink~),

~~~~~~~~~~~~~~~~~~CHAIN\_END~);~
\end{lyxcode}
This leads to an empty chain, because all modules (with the exception
of the \emph{STFA} and the \emph{block} module) have an input- and
output-size of 0. So we need to set one module to a given size:

\begin{lyxcode}
swr\_sdb\_set\_config\_int(~sink,~''size'',~128~);~
\end{lyxcode}
And while we're at it, we can tell the \emph{sink} module, that it
should count the occurences of the different values:

\begin{lyxcode}
swr\_sdb\_set\_config\_int(~sink,~''flag'',~2~);~
\end{lyxcode}
For further explanation, you can turn to the explanation of the \emph{sink}
module.

Now that the chain has been created and configured, it still needs
to be activated at least once, so that something happens:

\begin{lyxcode}
swr\_sdb\_seng\_msg(~rnd,~SUBS\_MSG\_USER,~NULL,~-1~);~
\end{lyxcode}
Which sends a user-defined message to the \emph{random} module. It
will now traverse the whole chain and the \emph{sink} module will
output the occurances of the different values. To compile and start
it, type the following commands:

\begin{lyxcode}
make

make~user~
\end{lyxcode}
As the size of the sink-input is only 128, this will not be very representativ
for the random-number generator. You may increase the size of the
sink-input to something like 65536 or even more, to see how the random-number
generator works.


\chapter{Using CVS}

In this chapter you'll get an overview of the CVS-structure we're using for
our software-radio. It is assumed that you already worked sometimes with CVS
and that you know about the basic ideas and advantages of CVS.

CVS stands for Concurrent Versioning System, and is the most widespread used
tool to make sure that a group of developers can access the code at the same
time without creating havoc. While it has some disadvantages, it is a
well-tested, stable tool that does its job right.

The first section talks about the structure used, while the other sections
talk about how to use the CVS with this structure.


\section{Structure}

Usually one has a structure with one primary \emph{Branch} where all
developers commit their changes to. In our case this was not desired, as
sometimes a developer changes huge structures during their work, and while
the changes last, the code is unstable. Furthermore the code has to run on
more than one machine at the same time, while needing localized compiling
under \emph{root}. This made it impossible to have a shared directory on all
machines. So, what we need is:

\begin{itemize}
\item{Seperate Development} by giving each developer an own Branch
\item{Distributing} of the new code using CVS-command 'up'
\item{Easy merging} through the CVS-command 'join'
\end{itemize}

The first two points are easily done in CVS. You can create branches, check
them out, and then work in these quite comfortably. The difficulty arises
when one tries to merge the changes back into the main-branch, perhaps even
from different developers.

Here is an overview about what is happening in a case when we want to synch
two branches, called \emph{Main} and \emph{Nicou}. "a", "b" and "c" are the
original versions of three files, while "b'" and "c'" are modified versions
of these files. "d" and "e" are new files that have been added later.

The 'server'-column displays what is stored on the cvs-server, that is,
whenever you call "cvs commit", your 'local' changes are stored on the
server, and with "cvs update", the changes stored in 'server' are written to
'local'.

\begin{tabular}{c|c||c|c}
\multicolumn{2}{c||}{Main} & \multicolumn{2}{c}{Nicou} \\
\hline
server&local&server&local \\
\hline
a b c&a b c&a b c&a b c \\
tag: lswN&&tag: lswM&
\end{tabular}

Both Main and Nicou start synchronized. They have a tag called \emph{lswN}
for the Main-Branch and \emph{lswM} for the Nicou-Branch. Now both work in
their respective Branch and check in their changes, and we get the following
picture:

\begin{tabular}{c|c||c|c}
&&&\\
a b' c d&a b' c d&a b c' e&a b c' e\\
&&&\\
\end{tabular}

The tag is still with the first version, that is "a b c". Now let's get the
changes from Main to Nicou:

\begin{lyxcode}
SRadio.Nicou> Conventions/synch
\end{lyxcode}

By taking the difference between \emph{lswN} and what is actually stored in
the Main-Branch, we get this:

\begin{tabular}{c|c||c|c}
&&&\\
a b' c d&a b' c d&a b c' e&a b' c' d e\\
&&&\\
\end{tabular}

Now it is very important not to commit these changes, because first we need
to take everything that has been changed in the Nicou-Branch to the
Main-Branch:

\begin{lyxcode}
SRadio.Main> Conventions/synch
\end{lyxcode}

And we get:

\begin{tabular}{c|c||c|c}
&&&\\
a b' c d&a b' c' d e&a b c' e&a b' c' d e\\
&&&\\
\end{tabular}

Now we can commit on both sides, writing the changes from 'local' to the
'server'. Then, we update the tags:

\begin{lyxcode}
SRadio.Nicou> Conventions/tag
\end{lyxcode}

and finally we get this picture:

\begin{tabular}{c|c||c|c}
&&&\\
a b' c' d e&a b' c' d e&a b' c' d e&a b' c' d e\\
tag: lswN&&tag: lswM&\\
\end{tabular}

Now we can start again with changing in both branches.


\section{Starting a new Branch}

There are two things to do when starting a new branch: first the new branch
has to be created, then the appropriate tags have to be written to the
cvs-tree.

Let's say we want to create a new branch called 'Brian'. For the first part,
it is enough to write in a checked-out Main-branch the following line:

\begin{lyxcode}
SRadio.Main> cvs tag -b Branch\_Brian
\end{lyxcode}

Then we have to make sure that everything is correctly tagged:

\begin{lyxcode}
SRadio.Main> Conventions/tag Brian
\end{lyxcode}

This is all that is needed. Now you can proceed to
\ref{sec:cvs_first_checkout} to see how to set up the system for the new user.


\section{\label{sec:cvs_first_checkout}Checking Out for the First Time}

It is a good idea to have the following set-up if you're not familiar
with CVS:

\begin{lyxcode}
brian@radio1:~> echo "export CVS\_RSH=ssh" >> ~/.bashrc
brian@radio1:~> echo -e "cvs -q$\backslash$nup -dP
$\backslash$ncommit -m ''" >
~/.cvsrc
\end{lyxcode}

Then you have to log out and log in again, so that these parameters are
available to your bash-shell. These commands help in everyday cvs. It might
also be more comfortable to run the tool SRadio.Brian/Conventions/lussh and
follow it's directions to create a password-less login to user 'sradio' on
lcmpc10.epfl.ch.

Now we can actually check-out a version of this new branch. For this,
change into the home-directory of brian, and write this:

\begin{lyxcode}
brian@radio1:~> cvs -d [e-mail]:/home/sradio/cvs co -r
Branch\_Brian SRadio\\
brian@radio1:~> mv SRadio SRadio.Brian
\end{lyxcode}

This gives you a check-out of the branch Brian in the directory SRadio.Brian.
All changes that are done in this directory are kept seperate from the other
parts of the software-radio, so you can commit and update at will, without
disturbing other developers.


\chapter{TODO}
\section{Writing a new Module}


\section{Writing a Test}


\section{Writing a new Radio}