howto.tex

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

Amp:~65:64,~Noise:~317:322~SNR~:~11.23~-~11.06~=~~0.16854

Amp:~66:63,~Noise:~421:393~SNR~:~10.14~-~10.15~=~-0.016712

Amp:~65:65,~Noise:~528:555~SNR~:~9.026~-~~8.83~=~~0.18867~
\end{lyxcode}
So you see that our method gives more or less the same results as
the \emph{snr} calculated in the \emph{matched\_filter}.


\section{Going Over the Air}

OK, now that the module is written, a simple test-case shows that
our module works (NOT), we can go on and write a simple radio that
transmits the SNR-slot and then receives it and shows the result.
We will make a simple radio that has a master, the BaseStation, that
transmits the synchronisation-signal, and a client, the MobileStation,
that synchronises to it and sends a SNR-slot in return.


\subsection{The Directories and Files}

It will be a radio, so we find the code in the directory \emph{Radios/SNR}.
The base for this radio is the simple-radio that can be found at \emph{Radios/Simple}
and contains the following files:

\begin{lyxcode}
simple\_radio.h

Makefile

BS/Makefile

BS/radio\_bs.c

MS/Makefile

MS/radio\_ms.c~
\end{lyxcode}
To reflect the fact that it isn't the \emph{simple} radio anymore,
we have to adjust the names in the Makefiles. The first lines in \emph{BS/Makefile}
contains:

\begin{lyxcode}
MODULE\_NAME~=~radio\_snr\_bs~

DEPENDS~=~rrc~synch~energy~mapper~midamble~random~\textbackslash{}

~~~~~~~~~~rndstr~spread~sink~cch~macro\_sch~snr~
\end{lyxcode}
and in \emph{MS/Makefile} reads:

\begin{lyxcode}
MODULE\_NAME~=~radio\_snr\_ms

DEPENDS~=~rrc~synch~energy~mapper~midamble~random~\textbackslash{}

~~~~~~~~~~rndstr~spread~sink~macro\_synch~macro\_sch~snr~
\end{lyxcode}

\subsection{README}

This file also reflects the changes and has a very small documentation
in it.


\subsection{MS/radio\_ms.c}

There is a lot of things to say about the basic system. You can find
an introduction in \ref{cha:A-Basic-System}. Here we just try to
focus on the things necessary to run our SNR-module over a real channel.

A very short simplification: when the mobile synchronises for the
first time to the base-station, it creates the necessary chains. This
happens in the function \emph{synchronised}. Near the end of this
function, you have to replace the declaration of the UP-chain with
the following chain:

\begin{lyxcode}
//~And~setup~a~simple~UP-chain...~~~

ch\_up~=~swr\_chain\_create(~

~~~~~~~~~~~~~~~~~~~~~~NEW\_SPC\_VAR(~\char`\"{}random\char`\"{},~rnd~),~

~~~~~~~~~~~~~~~~~~~~~~NEW\_SPC(~\char`\"{}snr\_send\char`\"{}~),~

~~~~~~~~~~~~~~~~~~~~~~NEW\_SPC(~\char`\"{}midamble\char`\"{}~),~

~~~~~~~~~~~~~~~~~~~~~~NEW\_SPC(~\char`\"{}rrc\char`\"{}~),~~

~~~~~~~~~~~~~~~~~~~~~~OLD\_SPC\_IN(~stfa,~1~),

~~~~~~~~~~~~~~~~~~~~~~CHAIN\_END~);~

swr\_stfa\_notice\_sdb(~stfa,~1,~rnd~);

PR(~\char`\"{}Ready~to~go\char`\"{}~);~
\end{lyxcode}
You see a new macro in the function \emph{swr\_chain\_create} here,
which is called \emph{OLD\_SPC\_IN} and uses the \emph{stfa} module.
The macro tells the function that this module has already been created
before. The module \emph{stfa} is quite important in the MSR: it creates
the link between the modules and the actual hardware. So an input
to the stfa is like a connection to the antenna.

As we don't know exactly when the mobile will be synchronised with
the base-station, we set the seed of the \emph{random} module every
frame to the same value. Like this we're sure that both the BS and
the MS have the same random-values. To achieve this, the function
\emph{do\_send\_up} is handy. It is called once in a frame, and we
can put the following line in there:

\begin{lyxcode}
swr\_sdb\_set\_config\_int(~rnd,~\char`\"{}seed\char`\"{},~0x1234~);~
\end{lyxcode}
That's it for the mobile-station part.


\subsection{radio\_bs.c}

This part of the radio sets up the chains for reception anyway and
then just waits on what happens. As it gives the synchronisation and
doesn't need to wait for it, it is much more simple than \emph{radio\_ms.c}.
So we can directly change the construction of the UP-chain in the
function \emph{start\_it} to:

\begin{lyxcode}
PR(~\char`\"{}Setting~uplink~in~slot~1\textbackslash{}n\char`\"{}~);~~~

ch\_rach~=~swr\_chain\_create(

~~~~~~~~~~~~~~~~~OLD\_SPC\_OUT(~stfa,~1~),~~~~~~~

~~~~~~~~~~~~~~~~~NEW\_SPC\_VAR(~\char`\"{}matched\_filter\char`\"{},~mafi~),~

~~~~~~~~~~~~~~~~~NEW\_SPC(~\char`\"{}snr\_rcv\char`\"{}~),

~~~~~~~~~~~~~~~~~CHAIN\_END~);

ch\_rach\_2~=~swr\_chain\_create(~NEW\_SPC\_VAR(~\char`\"{}random\char`\"{},~rnd~),

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~OLD\_SPC\_IN(~snr\_rcv,~1~),

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~CHAIN\_END~);

swr\_sdb\_set\_config\_int(~sch,~\char`\"{}mafi0\char`\"{},~mafi~);

while~(~looping++~)\{

~~usleep(~1000000~);

~~PR(~\char`\"{}mafi0:~\%g,~mafi1:~\%g\textbackslash{}n\char`\"{},

~~~~~~swr\_sdb\_get\_stats\_double(~mafi,~\char`\"{}snr\char`\"{}~),

~~~~~~swr\_sdb\_get\_stats\_double(~snr\_rcv,~\char`\"{}snr\char`\"{}~)~);

\}
\end{lyxcode}
One last important thing we don't have to forget: once a frame we
have to tell the random-module to generate some data. This is best
done in the function called \emph{do\_send\_down}, which is used once
a slot. So we can insert there:

\begin{lyxcode}
swr\_sdb\_set\_config\_int(~rnd,~\char`\"{}seed\char`\"{},~0x1234~);~~~

swr\_sdb\_send\_msg(~rnd,~SUBS\_MSG\_USER,~NULL,~-1~);~
\end{lyxcode}

\subsection{Running it with the channel-simulation}

Again, to help track down errors, it is more adviseable to run it
first in simulation-mode, like this you can track down errors much
more simple. In order to do so, change to the directory \emph{Radios/SNR}
and type \emph{make} to compile it, and \emph{make server; make show\_bsms}
which should bring up two windows, one showing the mobilestation and
another showing the basestation. If something goes wrong with the
compilation, fix it and run \emph{make} again. If something goes wrong
with the display, type \emph{make kill; make cleanproc} which should
clean-up the directories, and then you can try \emph{make server;
make show\_bsms} again.


\subsection{Running the real thing}

Now that you did all this work and the modules returned some decent
values, you can be pretty sure that it shouldn't run havoc in real-time
mode. So let's try it. First, you have to run the radio on the basestation,
issuing a \emph{make rf\_show} from the \emph{Radios/SNR/BS} directory.
Then, on the other machine, you can run \emph{make rf\_show} from
the \emph{Radios/SNR/MS} directory. If everything is set up correctly,
the hardware is OK and all things are nicely connected and plugged
in (this will give another chapter or two, installing the hardware),
you should again see two windows, one from the basestation and one
from the mobilestation, and the values this time are REAL values.
If you come this far, congratulations!

\index{From Conception to Measurement|)}


\chapter{Tools}

A couple of different tools exist for the MSR, to show the internal
state of the MSR, to act as a channel-server or build LDPC-codes.
In this chapter you'll learn about the different tools and how to
use them more accurately. If you have trouble with a tool, you can
read here if you find some help.


\section{\label{sub:Visualize}Visualize}

This tool is used to show the internal state of the MSR. It depends
on the STFA-module to draw the other signal-processing modules. So,
if there is no STFA module in the chain (which is the case for most
of the programs in the \emph{Test}-directory), Visualize can't show
the complete chain.


\subsection{Starting it}

To run it, simply type \emph{make show} and enter. This sets up the
path so that the \emph{qwt} library can be found. The executable first
searches for a real-time MSR that puts its data into \emph{/proc/sradio},
then it searches for the most recent entry in \emph{/tmp/username/proc.{*}}
If it doesn't find any of these, it stops with an error. Optionally
you can also give a path to the \emph{sradio/sdb/} directory on the
command-line.

Once the correct path has been found, the different modules are displayed
on the screen. Optional modules that are not connected to anything
are not shown on the screen. The whole display is updated once a second.


\subsection{Mouse handling}

With the left mouse-button you can drag around the whole screen, which
is mostly useful on small screens, when not all chains fit on the
screen.

The right mouse-button opens an option to exit the program when pressed
on an empty part of the visualize-display. When pressed over a module,
a menu pops up, where you can choose different display-options: stats
and outputs. If a module has more than two stats-entries, you can
choose which ones to display by choosing the corresponding entries.
Each selected entry is put on top of the list of stats inside the
block representing the module. Some of the stats-entries represent
blocks of data, which will be displayed in a window apart.


\subsection{\label{visualize_plotting}Plotting of values}

There is a possiblity to plot the \emph{stats}-values into a seperate
window. This can be used to log values of a certain module, or even
to draw plots of one value agains the other. In order to create a
plot, go to the \emph{File} menu and chose \emph{Stats Plot XY} or
\emph{Stats Plot Y(t)}. Now you can click on a module in order to
get a list of \emph{stats} that shall be plotted. If you chose \emph{Stats
Plot XY}, you have to chose a second module and a second \emph{stats}.
Once the stats have been chosen, the plot-window updates once a second
with a new value.

You can chose a new value for the udpate-time. The time is given in
1/100s of seconds. Be aware that for performance reasons the screen-update
is only twice a second, even if the data-update-value is less than
50. No samples will get lost, only the update will appear slow. To
enable long measurements without degrading performance of the \emph{visualize}
tool, only the 1000 most recent samples are shown. This assures that
you can have 1 million or more samples, and still have \emph{visualize}
react to your requests. If you chose to \emph{export to matlab}, all
samples will be exported. If you chose \emph{export to ps}, only the
visible samples will be plotted.


\subsection{\label{visualize_exporting}Exporting values}

Each plot-window has the possibility to export the values either as
a postscript-file or to a matlab-file. In order to have a small preview
of the data you'll export, you can click on the graphic. This will
freeze the update, and allow you to 'chose' which data you want to
export. 

If there is lots of data, a general update will only show 1000 samples.
When you click on the 


\subsection{Known bugs}

During simulation-mode,it may be that an update of the screen occurs
at the same time as an update from the MSR, which results in broken
or incomplete chains. Usually this should 'heal' during the next update.

If the same happens with a plot-window, it may be that you have to
close this particular window, and reopen it again.


\section{\label{sub:Channel-server}Channel-server}

The channel-server takes the inputs of different radios, mixes them
together and sends them back to the different radios.


\subsection{Starting it}

When you're in the \emph{Main/} structure somewhere, usually it is
enough to type \emph{make server} to start the channel-server. This
is only necessary once.


\subsection{Known bugs}

For the moment the channel-server and the simulations have to be run
on the same computer.

If you change something in the implementation of the channel-server,
you have to restart it. The most simple way is to type \emph{killall
server} followed by a \emph{make server}.


\section{\label{sub:LDPC-code-generation}LDPC-code generation}

In \emph{Tools/LDPC} you find a program that takes descriptions of
LDPC-codes and puts them in a module-readable way.


\subsection{Starting it}

First you need some descriptions of LDPC-codes. For this you have
to ask Abdelaziz on how to do this. Then you can type \emph{write
code1 code2} for putting \emph{code1} and \emph{code2} into a file
called \emph{graphs.c} which has to be copied into \emph{Modules/Coding/LDPC}.
After a recompilation you're ready to use the new codes.


\subsection{Known bugs}

The length of the code is fixed for the moment at 4000 bits.


\section{Output data-blocks}

A small program called \emph{convert} has the ability to read out
any port or any stats-block that is defined in a running software-radio,
be it a simulation or a real-time run. It does this by reading out
the tree generated by the software-radio. This tool is now more or
less obsolete, as the visualize-tool has the ability to export data-structures
from any module.


\subsection{Syntax}

convert dir {[}-h{]} {[}-o file{]} {[}-p{]} {[}nr{]}

The \emph{dir} parameter has to point to the appropriate directory,
which is \emph{/proc/sradio/sdb} or \emph{/tmp/proc.n/sradio/sdb}.
Upon running convert with only the directory, it outputs a list of
available modules in this directory. You have to add the id of the
desired module to the path, and then you can run \emph{convert} again.
If you run it without the \emph{-p} option, it will tell you what
stats-blocks are available, with the \emph{-p} option, it will output
a list of all available output-ports and their types. Now you can
run \emph{convert} one last time, adding the index of the stats-block
or the output-port you want to look at, and probably redirecting the
output into a file. This file can be read directly by \emph{octave}.
You can also add \emph{-o file} to set the output-filename.


\chapter{Debugging}

In a perfect world we wouldn't need this chapter. In a realistic world,
however, one has to take into account possible errors. While every
care has taken to make the framework of the MSR as error-free as possible,
there still are bugs left. For sure. But usually they are difficult
to find. So, if your module doesn't work, chances are big that you
don't use the framework as it's supposed to be. This chapter will
help you finding where the bug is. It is then up to you to find how
it has to be fixed.


\section{Debugging in user-space}

A big advantage of user-space is the fact that the channel-server and all
radios can be stopped and restarted at will, without loosing synchronisation.
This is why it is encouraged to do good testing and debugging in user-space,
before running things in real-time.

This section gives an overview of how to use the GDB to detect some simple
errors, like division by zero, $\log(0)$ or other exceptions.

\subsection{Using Gdb with Tests}

The first thing to do when a module doesn't run and stops with a \emph{segmentation
fault} is to use \emph{make debug} instead of \emph{make user}. This
will call the GNU-debugger, run the module and stop on the offending
instruction. The most common commands after this are:

\begin{lyxlist}{00.00.0000}
\item [ba]show the backtrace, where the most recent function is on top 
\item [print]prints a variable of the current context 
\item [up]moves one function deeper on the stack. If it stops on a function
you don't know, you can use \emph{up} a couple of times until you
are in the MSR 
\item [list]lists the current context. Takes as argument a file and it's
line-number, like \emph{list sdb.c:234}
\end{lyxlist}


\subsection{Debugging a Simulation}

When running a simulation of two radios, the above doesn't work anymore. You
have to start a channel-server, and the two radios. The most simple way to so
is to run the server and the BS in one window, and the MS in another window. If
you need the visualize-tool to crash the system, you can start it in a third
window, after the BS and MS are started. shell1, shell2 and shell3 denote three
different windows or shells.

\begin{lyxcode}
shell1:SRadio/Radios/Simple/BS\$ make server debug