reference.tex

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

\part{Reference-Manuals}


\chapter{Overview}

In this part you find a complete as possible reference to all parts of the
software-radio. If you're interested in one of these components, be sure to
read about the corresponding subject in the architectural part.

\begin{itemize}
\item{GUI} shows an overview of the classes used in the \emph{Visualize}
program
\item{Signal Processing} gives more details about the CDB and SDB, as well as
the subsystem and the modules
\item{Antenna} what a driver has to implement in order to be used
\item{Hardware} how to set up the hardware
\item{Modules} a detailed description of the most often used modules
\end{itemize}


\chapter{GUI}

\index{Visualize!Reference|(}
 The Graphical User Interface for the software-radio is called
\emph{Visualize}, as it visualizes the internal structure and state of the
modules. Furthermore it's possible to change configuration-parameters of the
modules in real-time, while it is running.

 This chapter is split into three sections: one for the general interface, one
for the interaction windows, and one for the more internal structures.

\section{General Interface}

 The main classes involved in displaying the main view are shown in figure
\ref{fig:visualize_interface}. Only the main subclassing from Qt is shown,
subclassing from QObject and such is not shown.

\begin{figure}[h]
   \centering
   \includegraphics[width=7cm, keepaspectratio]
   {figures/visualize_interface}
   \caption{The classes involved in bringing up the main view}
   \label{fig:visualize_interface}
\end{figure}

\index{Visualize!Classes!Interface}
 There is one main-window, even if there are multiple radios to display. The
main window, created by \emph{Interface}, contains a \emph{QTabWidget} with a
tab for every active radio. If there is only one active radio, no tab will be
shown.

\index{Visualize!Classes!RadioView}
 Each active radio that is show is served by a \emph{RadioView} module which is
the active \emph{QWidget} for the corresponding tab. The RadioView updates the
display once a second, and stops updating if it is not the active tab. While
updating it checks for new or removed modules and asks each module to update
the values shown in it's body.

\index{Visualize!Classes!ModuleGenerator}
 Each RadioView instance has it's own \emph{ModuleGenerator}. On instantiation,
the ModuleGenerator lists all available module and tries to determine which one
is the main-module. In the most common situation, this will be a \emph{stfa},
but it might be another module. The main-module is very important for the
Mapper. For further updates, only added modules are taken into consideration.

\index{Visualize!Classes!CanvasView}
 All modules are drawn upon a \emph{CanvasView}, which is subclassed from
\emph{QCanvasView}. CanvasView's main job is to create the context-menu when
the user clicks the right mouse-button, as well as to move the canvas when the
user drags it with the left mouse-button.

 The \emph{Visualize!Classes!Mapper} has a reference to all modules. He also
figures out the
position and connections of all modules, so that they fit nicely onto the
CanvasView \footnote{Here is a possibility to rewrite a class}. The main-module
is called \emph{stfa}. As we only show one channel at a time, the Mapper needs
also to know which is the current channel.

\index{Visualize!Classes!Module}
 Finally the \emph{Module} represents the software-radio module with respect
to all needed functionalities. It draws itself with the name and the chosen
stats-parameters, including the pads for the connections; it can bring up
windows for output- and stats-signals; it can ask the software-radio module to
perform the signal-processing\footnote{This is only useful in debugging-mode}.

 Between all these modules a number of signals are passed in order to minimize
the cross-module method calls.


\section{Interaction}

 There are a number of ways the user can interact with the GUI:
\begin{itemize}
\item Chosing the stats to be displayed on the module
\item Showing a stats-graphic
\item Showing a graphic of an output-port
\item Configuring values of a module
\item Plotting stats-values
\end{itemize}
 
 The active classes in doing this are shown in figure
\ref{fig:visualize_display}. The following list gives an overview of the used
modules and their function, for a more detailed description, refer to the
following subsections.
\begin{itemize}
\item{Interface} is the head of the visualize-tool and is the only one to have
access to the menus
\item{Module} represents a software-radio module
\item{Block} is the virtual class for the (output)port, stats and plot
\item{Port} knows how to read data from an output-port
\item{Stats} reads a stats-'block' that represents some data
\item{Plot} has a flexible data-part that can grow over time
\item{ConfWind} shows a window with all configuration-options of the module
\item{Image} is a special stats-'block' representing an image
\item{Show} allows a Block to be displayed, complete with all control-widgets
necessary
\item{PlotWin} takes care of chosing the stats to be displayed
\end{itemize}

\begin{figure}[h]
   \centering
   \includegraphics[width=7cm, keepaspectratio]
   {figures/visualize_display}
   \caption{The different display-options}
   \label{fig:visualize_display}
\end{figure}

\subsection{Plotting}

 There are two possibilities of plotting: Y(t) and XY. The former takes only
one stats-argument and displays it in time, while the latter displays one
stats-argument as the function of a second one.

\index{Visualize!Classes!PlotWin}
 Once the user has chosen one of the two plotting-methods, the Interface class
instantiates a \emph{PlotWin} and sets up the signals so that the PlotWin will
be informed whenever the user clicks on a module.

 It is the software-radio that takes care of reading the stats-values and
putting them into a list. The PlotWin class reads this list once a second and
updates its internal values with the values read from the software-radio.

 In a clean implementation, PlotWin would be a subclass of Show, but as PlotWin
needs an initialised window to work with, this is not possible.

\subsection{Configuration}

\index{Visualize!Classes!ConfWind}
 If the user requests a reconfiguration of a module, a \emph{ConfWind} class is
instantiated and given the authority to change configuration parameters. The
ConfWind acts independantly on changes from the user and transmits them to the
software-radio.

\subsection{Signal and Outputs}

\index{Visualize!Classes!Show}
 Both require the Module to instantiate a \emph{Show}, but give it either a
Port or a Stats as argument. Show takes care of letting the user chose the
method to display the signal (real, imaginary, complex, absolute, fft), zoom in
and out, freezing and exporting to postscript and matlab.

\subsection{Image}

\index{Visualize!Classes!Image}
 Althogh \emph{Image} is a stats-variable, it is implemented as a class on its
own\footnote{One could subclass it from Block and tell Show how to treat an
image}. When the module is asked to show a stats, it decides whether it has to
put an Image in a QMainWindow or a Show.

 The Image-class takes care itself about updating and preparing the data for
display.


\section{Internal}

 These classes deserve some more specific treatement.

\subsection{Mapper}

\index{Visualize!Classes!Mapper}
 The mapper is described in a report of the students who wrote it. The report
can be found in the software-radio tree under
$$SRadio/Documentation/Report/Visualize.ps.bz2$$

 Although the report is not up-to-date with most of the software-radio, the
mapper has never been updated in the meantime. So everything described in the
report with regard to the mapper is still accurate.

\subsection{\label{sec:fifocmd}FifoCmd}

\index{Visualize!Classes!FifoCmd}
 This is the link with the software-radio. The counterpart is in
SRadio/Base/DBG/*. All possible requests and changes to the configuration are
described by this class.

\subsection{Module}

\index{Visualize!Classes!Module}
 Together with the Mapper, this is one of the main classes. Its tasks consist
of:
\begin{itemize}
\item{Draw} itself on the canvas with the name and the chosen
stats-parameters, including the pads for the connections and eventual
performance-measurements
\item{Show} windows for output- and stats-signals, as well as configuration
\item{Process} some data of the module. This is mostly useful in debugging-mode
and for test-cases. It corresponds to a \emph{call\_module} in the
software-radio.
\end{itemize}
\index{Visualize!Reference|)}


\chapter{Signal Processing}



\section{CDB}
\index{CDB!Reference|(}

\index{CDB!Reference|)}
\section{SDB}
\index{SDB!Reference|(}

\index{SDB!Reference|)}
\section{Subsystem}
\label{sec:sp_subsystem}
\index{Subsystem!Reference|(}

As written in \ref{sub:spc_subsystem}, the subsystem is the base-class for all
modules. As such it is responsible for correct message-passing and cleaning up
of the modules. Furthermore it keeps track and acts upon different flags that
may be set in the subsytem and the ports. So there are three places that
describe more or less entierly the state of the subsystem:
\begin{itemize}
\item{Messages} which are passed between subsystems\footnote{Subsystem and
Module are interchangeable in this context}
\item{Subsystem-flags} reflecting the state of the subsystem
\item{Port-flags} showing the state of each port individually
\end{itemize}

In the following three subsections you'll find a description of each of these
systems.

\subsection{Messages}
\index{Messages}

Each message that is passed to a subsystem has three arguments: message-id,
data and return-id. The message-id tells the subsystem what it needs to do. The
data-part is a (void*)-pointer, and should be set to NULL when it's not used.
The return-id is used when a return-message could be generated, and should
contain the sender-id. If the sender has no id (is not a module), the sender-id
should be set to -1.

The messages defined in the message-id can be divided in three groups: 
\begin{itemize}
\item{Basic handling} involves everything to set-up the module and is rarely or
never called during life-time
\item{Reconfiguration} of the module is also pretty rare for most of the modules
\item{Data Propagation} is the workhorse of the subsystem and modules
\end{itemize}
Each group is described in more detail in the following sections.

\subsubsection{Basic Handling}

After the initialisation of a subsystem, everything is ready to connect this
subsystem to another subsystem. 

\index{SUBS\_MSG\_*|see{Subsystem/Messages}}
\index{Subsystem!Messages!SUBS\_MSG\_CONNECT}
 Connecting is done by sending the message \emph{SUBS\_MSG\_CONNECT} to both
subsystems that are to be connected together. As payload for the message one
should give a structure of type swr\_propagation\_t. This structure contains
all necessary information: port-\#, size, flags, block-address, sdb-id of the
other end and the direction. If one of the ports is already defined with regard
to its size, it will communicate this to the connect-function, which will
inform the other port of the desired size.

\index{Subsystem!Messages!SUBS\_MSG\_DISCONNECT}
The \emph{SUBS\_MSG\_DISCONNECT} message works in a similar way. One has to
take care that both messages don't inform the other subsystem of the change. A
function wanting to connect or disconnect two modules has to inform both of the
action to take.

\index{Subsystem!Messages!SUBS\_MSG\_NEW\_TRACK}
\index{Subsystem!Messages!SUBS\_MSG\_NO\_TRACK}
The user can ask for tracking of certain values. Whenever a subsystem is asked
to track its values, it is sent a \emph{SUBS\_MSG\_NEW\_TRACK} message, after
which the subsystem will check the tracking-list on each data-processing to
update the corresponding tracks. Similarly, \emph{SUBS\_MSG\_NO\_TRACK} is sent
to tell the subsytem to stop searching the tracking-list. This pair of messages
exists because tracking is quite rare and asks for some processing-power in
order to update all necessary lists. So, as long as the subsystem didn't
receive a SUBS\_MSG\_NEW\_TRACK-message, it won't search through the list.

\index{Subsystem!Messages!SUBS\_MSG\_THREAD}
Even though the software-radio is conceived as a real-time radio, some modules
take more time because of their complexity. In order to assure that the rest of
the software-radio is not affected by a complex module, it is possible to put
the module in a thread by sending it a \emph{SUBS\_MSG\_THREAD}\footnote{This
is not the default setting, because threading of a module gives a sensible
overhead}. When receiving this message, the subsystem sets up a thread and will
activate this thread whenever it receives a SUBS\_MSG\_DATA message. For all
other messages, the subsystem will run in the context of the calling function.

\index{Subsystem!Messages!SUBS\_MSG\_EXIT}
Finally, a subsystem will stop working upon receiving a
\emph{SUBS\_MSG\_EXIT}-message. All input- and output-ports have to be cleaned
up before sending this messasge, otherwise undefined behaviour might occur.


\subsubsection{Data Propagation}

\index{Subsystem!Messages!SUBS\_MSG\_PREPARE}
In a multi-threaded real-time environment one has to take care that things
don't get mixed up. For this reason, before asking a module to do some
calculations on data, one has to send it a \emph{SUBS\_MSG\_PREPARE}-message.
This message is propagated to all connected outputs where it is further
propagated. If any of the connected modules is still working, the message
returns a SUBS\_STATUS\_WORKING, and the caller should wait for a later time.

\index{Subsystem!Messages!SUBS\_MSG\_DATA}
If the prepare-message returned 0 (for OK), that means that all modules in the
chain are prepared and can be called by sending a
\emph{SUBS\_MSG\_DATA}-message to the top module. This message will test for
SUBS\_STATUS\_MULTI\_IN and SUBS\_STATUS\_THREAD and react accordingly. If
appropriate, it will call the pdata-function of the module. Upon returning, the
output-ports are checked for new data, and the modules connected to
output-ports containing new data are sent a SUBS\_MSG\_DATA-message.

\index{Subsystem!Messages!SUBS\_MSG\_PING}
A small test-message that survived from the depths of the development is the
\emph{SUBS\_MSG\_PING}-message, which has no direct effect on the subsystem.

\index{Subsystem!Messages!SUBS\_MSG\_USER}
In order to allow for user-defined messages to the modules, the
\emph{SUBS\_MSG\_USER}-message exists. The payload of the message can contain
whatever is accurate. Upon reception of this message, the user\_msg-function of
the module is called, with the payload as argument.


\subsubsection{Reconfiguration}

\index{Subsystem!Messages!SUBS\_MSG\_RECONFIG}
Whenever a part of the software-radio thinks that the configuration might
have changed, it sends a \emph{SUBS\_MSG\_RECONFIG}-message to the
corresponding module. If the receiving module has the flag
SUBS\_STATUS\_RECONFIG set, it will call the reconfig-function of the module.
Furthermore the configure\_inputs or configure\_outputs-function is called,