reference.tex

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

\subsubsection{module\_init}

This function is a bit special in that it only registers the module
with the CDB and doesn't do any actual signal-processing. So these
are the macros you can use:

\begin{lyxlist}{00.00.0000}
\item [UM\_CONFIG\_INT]adds an int-parameter to the configuration 
\item [UM\_CONFIG\_COMPLEX]adds a complex-parameter to the configuration 
\item [UM\_CONFIG\_DOUBLE]adds a double-parameter to the configuration 
\item [UM\_CONFIG\_DOUBLE\_COMPLEX]adds a double\_complex-parameter to the
configuration 
\item [UM\_CONFIG\_STR128]adds a char{[}128{]} parameter to the configuration 
\item [UM\_CONFIG\_POINTER]adds a void{*} parameter to the configuration 

\item [UM\_STATS\_INT]adds an int-parameter to the statistics 
\item [UM\_STATS\_COMPLEX]adds a complex parameter to the stats
\item [UM\_STATS\_DOUBLE]adds a double-parameter to the statistics 
\item [UM\_STATS\_DOUBLE\_COMPLEX]adds a double\_complex-parameter to the
statistics 
\item [UM\_STATS\_STR128]adds a char{[}128{]} parameter to the statistics 
\item [UM\_STATS\_POINTER]adds a void{*} parameter to the statistics 
\item [UM\_STATS\_BLOCK]adds a block\_t parameter to the statistics, see
\ref{par:Blocks}
\item [UM\_STATS\_IMAGE]adds an image to the stats

\item [UM\_INPUT]adds an input-port, for the types see
\ref{sub:Data-types-for-inputs},
and allows to define a flag 
\item [UM\_OUTPUT]adds an output-port, for the types see \ref{sub:Data-types-for-inputs},
and allows to define a flag 
\end{lyxlist}

\subsubsection{other functions}

\begin{lyxlist}{00.00.0000}
\item [private]allows access to this modules private-structure 
\item [size\_in(n)]returns the input-size of the port \emph{n}. This may
also be used to assign a size to a port, so \emph{size\_in(0)=256;}
is valid. 
\item [size\_out(n)]returns the output-size of the port \emph{n}. Allocating
sizes is possible as with \emph{size\_in}. 
\item [data\_available(n)]returns true if the input-port \emph{n} has some
new data 
\item [buffer\_in(n)]returns a pointer to the input-buffer \emph{n} and
clears the data-flag on this input-port 
\item [buffer\_out(n)]returns a pointer to the output-buffer \emph{n} and
sets the data-flag on this output-port 
\item [private]points to the private part of the module
\item [call\_module]sends a MSG\_DATA to the module
\item [make\_thread]puts a module in a thread
\end{lyxlist}

\chapter{Makefile}


\section{\label{sub:Make-Parameters}Make Arguments}

Whenever you are in a sub-directory of the software-radio, you can
give some arguments to the \emph{make} command. There are arguments
that may be used everywhere in the tree, some that are only valid
in the \emph{Radios/{*}} subdirectories and some arguments that are
only valid in the subdirectories that contain code.


\subsection{Common}

These arguments may be used anywhere in the tree (except the \emph{Tools}-directory):

\begin{lyxlist}{00.00.0000}
\item [clean]Remove all object-files in all sub-trees
\item [whole]Re-compile the whole tree
\item [base]Re-compile base only
\item [tools]Re-compile tools only
\item [modules]Re-compile modules only, additionally \emph{mod\_coding},
\emph{mod\_data}, \emph{mod\_general}, \emph{mod\_macro}, \emph{mod\_signal}
re-compile only this special modules-directory
\item [show]Starts the visualisation-tool
\item [server]Start the channel-server 
\item [kill]End all simulations as well as the channel-server 
\item [cleanproc]Remove all simulation-directories from \emph{/tmp}
\item [rmall]Unloads all real-time modules and stops RTLinux 
\item [cvs\_up]Updates the \emph{whole} SRadio/*-tree using CVS
\item [cvs\_commit]Commits \emph{all} changes to the SRadio/*-tree
\end{lyxlist}

\subsection{Radios}

Arguments that can be used in the subdirectories of \emph{Radios/}

\begin{lyxlist}{00.00.0000}
\item [bsms]Starts channel-server and both BS and MS part. To stop, run
\emph{make kill}
\item [show\_bsms]Like \emph{bsms}, but also runs the visualisation-tool 
\item [wait\_bsms]Like \emph{bsms}, but stops the MS after 20 seconds and the
BS after 30 seconds. Most useful to check whether a radio exits nicely,
before trying it in real-time
\item [short\_wait\_bsms]Like \emph{wait\_bsms} but for the impatient: BS
waits for 10 seconds, MS for 5 seconds. Attention: things might not be
correctly initialised after 5 seconds!
\end{lyxlist}

\subsection{Code}

Useful arguments when you are developing code

\begin{lyxlist}{00.00.0000}
\item [user]Loads the modules defined in the Makefile for simulation and unloads them
\item [user\_show]Like \emph{user}, but also starts the visualisation-tool 
\item [user\_wait]Like \emph{user}, but doesn't unload the modules
\item [user\_wait\_5]Like \emph{user}, but waits for 5 seconds before
unloading
\item [user\_wait\_10]waits for 10 seconds before unloading
\item [user\_wait\_20]waits for 20 seconds before unloading
\item [user\_wait\_30]waits for 30 seconds before unloading
\item [user\_wait\_60]waits for 60 seconds before unloading
\item [ddd]Start the graphical debugger in simulation-mode 
\item [debug]Start gdb in simulation-mode 
\item [rf]Starts the radio in real-time mode 
\item [rf\_tail]Like \emph{rf} but also tails \emph{/var/log/messages}
where \emph{PR\_DBGs} will be written to 
\item [rf\_show]Like \emph{rf\_tail} but launches the visualisation-tool 
\item [rmall]Unloads all modules from real-time mode
\end{lyxlist}


\chapter{DBG-interface}
\label{chap:dbg-interface}

\section{Command-syntax}

\subsection{list}
returns a list of all available modules
\paragraph{Arguments}
none
\paragraph{Returns}
a module\_id,name list of all modules available, where module\_id is to be
used for reference, while name reflects the spc-name of the module. The
returned list is sorted on module\_id.


\subsection{show\_all}
gives the whole description of a module
\paragraph{Arguments}
the id of the module
\paragraph{Returns}
\begin{itemize}
\item [input] number of inputs, followed by a type,len - list for every
input
\item [output] number of outputs, followed by a conn\_id,conn\_index,type,len
list for every output, where conn\_id and conn\_index point to the module and port
connected. If this port is not connected, conn\_id and conn\_index are both -1.
\item [config] number of configs, followed by a name,type,value - list for every
configuration-item.
\item [stats] number of stats, followed by a name,type,value - list for every
configuration-item.
\end{itemize}


\subsection{show\_*}
Returns only part of the description. "*" can be one of \{input, output,
config, stats\} and will return the corresponding information.
\paragraph{Arguments}
the id of the module
\paragraph{Returns}
Like \emph{show\_all}, but only the asked argument

\subsection{get\_output}
returns a given output of a given module
\paragraph{Arguments}
module\_id,port\_nbr
\paragraph{Returns}
size,type,values where values are decimal, comma-seperated values. For complex
numbers, each value is a (real,imag)-pair.



\subsection{set\_config}
Sends a new config-value
\paragraph{Arguments}
module\_id, config\_index, value

value is in human-readable form.
\paragraph{Returns}
"Reconfigured" on success

  
\subsection{get\_block}
Returns the values of a block. Contrary to "show\_stats" and "show\_config",
"get\_block" returns the values in their binary form.
\paragraph{Arguments}
module\_id, stats\_index
\paragraph{Returns}
The block of data in binary representation.

  
\subsection{get\_image}
Returns an image that is stored in a stats. Read \emph{Returns} for a
description of the values returned.
\paragraph{Arguments}
module\_id, stats\_index
\paragraph{Returns}
The image in binary representation. The size of the returned block is of
$width * height * \lceil\frac{bpp + 7}{8}\rceil$. That means that a 20 x 20
black/white image ($bpp=1$) will return 400 bytes.


\subsection{new\_list}
A list is used when one wants to track a certain value in the software-radio,
or a value-pair. The software-radio tries its best to make sure that all
value-pairs are correlated, but it may happen that an older value gets paired
with a new value.
\paragraph{Arguments}
module\_id$_1$, sats\_index$_1$, module\_id$_2$, stats\_index$_2$

If module\_id$_2$ is $-1$ then only a single value will be tracked and the
values returned by \emph{read\_list} will contain a \{value,time\} pair.
\paragraph{Returns}
The id of the list, in ascii


\subsection{read\_list}
Returns the so far collected value-pairs. The cache is of length 1024, that
means that you should collect the data before 1024 are stored. In the most
busiest scenario, this means once every second.
\paragraph{Arguments}
list\_id
\paragraph{Returns}
The first line contains the total number of value-pairs that will be sent.
Then follow either (value$_1$, value$_2$) or (value, time) pairs, each one
followed by a "\\n".


\subsection{close\_list}
Finishes tracking of the values from this list.
\paragraph{Arguments}
list\_id
\paragraph{Returns}
OK or error on error.


\subsection{process\_data}
Tells a module to immediatly start processing. If the module has inputs, all
connected inputs will be activated before processing.
\paragraph{Arguments}
module\_id
\paragraph{Returns}
OK on success


\subsection{ping}
To test whether the software-radio is still running and replying to requests.
\paragraph{Arguments}
none
\paragraph{Returns}
"pong"



\chapter{Signal Flow}

For a correct understanding of what happens in the software-radio and where
to insert a new module, it is very good to have an overview of the
signal-flow that goes through the radio. As of the writing of this chapter,
new hardware is being installed in our lab. For this reason, this chapter is
seperated into three sections:

\begin{itemize}
\item{Common} the common signal-flow
\item{ICS-hardware} the signal-flow specific to the ICS-cards
\item{STM-hardware} the signal-flow specific to the STM-cards
\end{itemize}


\section{Common}

\begin{figure}[h]
\begin{center}
\includegraphics[width=5cm, keepaspectratio]
{figures/signal_common}
\caption{\label{fig:signal_common}The common part of the signal-flow}
\end{center}
\end{figure}

In figure \ref{fig:signal_common} you see an overview of the most common
architecture when building a software-radio. On the left-hand side you see
the transmitting modules while on the right-hand side the receiving modules
are located. Each transmission is built around a \emph{slot} which is a
constant time-slice in the transmission.

\subsection{Sending}

The most common implementation starts with two blocks that have bits as
output. The \emph{Source} may be anything, from a pseudo-random sequence to a
part of a network-transmission.
 
 These bits go through a \emph{Coding} block, where redundant information
is added, in order to assure some error-resistance when receiving the data.
The ouput of this operation are again bits. For the coding we have
ldpc-codes, convolutional-codes or spreading-sequences which allow also for to
seperate multiple users if they send at the same time-instant.

\begin{figure}
\begin{center}
\begin{tabular}{cc}
\begin{minipage}{50mm}
\includegraphics[width=50mm,keepaspectratio]
{figures/QPSK_space}
\caption{\label{fig:qpsk-signal-space}QPSK signal space}
\end{minipage}
&
\begin{minipage}{50mm}
\vspace{45mm}
\includegraphics[width=50mm, keepaspectratio]
{figures/midamble}
\caption{\label{fig:midamble}Position of the midamble}
\end{minipage}
\end{tabular}
\end{center}
\end{figure}

After the coding, the bits get \emph{Mapped} into symbols. The most common
mapping is a QPSK-mapping, where two bits define one symbol, as can be seen in figure
\ref{fig:qpsk-signal-space}. The mapper-module supports also other
PSK-mappings or QAM-mappings. But commonly the QPSK-mapping is used.

In the middle of this block, a test-sequence is inserted which is called
\emph{Midamble}, because of it's position in the block, as can be seen in
figure \ref{fig:midamble}. The goal of this test-sequence is to be able to
estimate the channel at the receiving end and to perform a matched filtering
afterwards, cancelling out any effects due to the channel.

Once these four basic operations are done, the block composed of complex
symbols goes through the hardware-specific part.

\subsection{Receiving}

Out of the hardware-specific part, we get again a block composed of complex
symbols. If we have a flat fading channel with only one tap, that is a direct
line-of sight, as well as a perfect synchronisation between the sending and
the receiving part (which is usually NOT the case), then this receivd symbols
would be the same as the sent ones.

In common transmissions, this is not the case. For this reason we have the
\emph{Matched Filtering}, where the midamble from the sending chain is used
to estimate the channel-parameters. Using these channel-parameters, one can