\documentclass[oneside,a4paper,english]{book}
%%\usepackage[french]{babel} %% Use your own babel language
\usepackage[top=3cm,bottom=3cm,left=2.5cm,right=2.5cm]{geometry}
\usepackage{ucs}
\usepackage[utf8x]{inputenc}
\usepackage{pslatex}
\usepackage{hyperref}
\usepackage{graphicx}
\usepackage{tabularx}
\usepackage{supertabular}
\usepackage{pdflscape} %% Used for very big table
\usepackage{moreverb}
\usepackage{color}
\usepackage{listings}
\usepackage{lastpage}
\usepackage{fancyhdr}
\usepackage{ulem}
\usepackage{textcomp}
\usepackage{wasysym}
\usepackage{wrapfig} %%Usefull for image 
\usepackage{fguill} %%Use this package for guillemot[left|right] useless with babel set to french
\usepackage{eso-pic} %% Background

%\usepackage[active]{srcltx}
\usepackage{times}
%\usepackage[latin1]{inputenc}
\usepackage{a4wide}
\setcounter{secnumdepth}{3}
\setcounter{tocdepth}{3}
\usepackage{graphicx}
\usepackage{makeidx}

\makeindex
\makeatletter
\hypersetup{
  linkbordercolor={1 1 1},
  urlbordercolor={1 1 1},
  linkcolor={0 0 0}
}

\pagestyle{fancy}%
\renewcommand{\headrulewidth}{0.1pt}
\renewcommand{\footrulewidth}{0pt}
\renewcommand{\chaptermark}[1]{%
	\markboth{\chaptername\ \thechapter.\ #1}{}}

\renewcommand{\sectionmark}[1]{%
	\markright{#1}{}}

\fancypagestyle{plain}{%
\fancyhf{}
\fancyfoot[R]{\thepage/\pageref{LastPage}}
\renewcommand{\headrulewidth}{0pt}
\renewcommand{\footrulewidth}{0pt}}
\fancyhf{}
\fancyhead[L]{\rightmark}
\fancyhead[R]{\leftmark}
\fancyfoot[R]{\thepage/\pageref{LastPage}}
\renewcommand{\headrulewidth}{0.1pt}
\renewcommand{\footrulewidth}{0pt}

\definecolor{codegray}{gray}{.95}
\lstset{language=C,
	numbers=left,
	tabsize=2,
	basicstyle=\scriptsize,
	stringstyle=\textrm,
	showstringspaces=false,
	frame=none,
	xleftmargin=3pt,
	backgroundcolor=\color{codegray}}

\newcommand{\settexitref}[2]{(\ref{#1}p\pageref{#1})}
\newcommand{\dokutitlelevelone}[1]{\chapter{#1}}
\newcommand{\dokutitleleveltwo}[1]{\section{#1}}
\newcommand{\dokutitleleveltree}[1]{\subsection{#1}}
\newcommand{\dokutitlelevelfour}[1]{\subsubsection{#1}}
\newcommand{\dokutitlelevelfive}[1]{\paragraph{#1}}
\newcommand{\dokufootnote}[1]{\footnote{#1}}
\newcommand{\dokufootmark}[1]{\footnotemark[#1]}
\newcommand{\dokubold}[1]{\textbf{#1}}
\newcommand{\dokuitalic}[1]{\textsl{#1}}
\newcommand{\dokumonospace}[1]{\texttt{#1}}
\newcommand{\dokuunderline}[1]{\underline{#1}}
\newcommand{\dokuoverline}[1]{\sout{#1}}
\newcommand{\dokusupscript}[1]{\textsuperscript{#1}}
\newcommand{\dokusubscript}[1]{$_{#1}$}
\newcommand{\dokuhline}{\line(1,0){400}}
\newcommand{\dokulabel}[1]{\label{#1}}
\newcommand{\dokuitem}{\item}
\newcommand{\dokuquoting}{\textbar}
\newcommand{\dokutabularwidth}{\textwidth}
\newcommand{\dokusupertabularheadbreak}{\small\sl continued from previous page}
\newcommand{\dokusupertabulartailbreak}{\small\sl continued on next page}
\newcommand{\dokuheadingstyle}[1]{\textbf{#1}}
\definecolor{dokuheadingcolor}{rgb}{0,0,0.60}
\newcommand{\dokubackground}[1]{%
%\AddToShipoutPicture{%
%  \AtTextCenter{%
%    \makebox(0,0)[c]{\resizebox{\textwidth}{!}{%
%      \rotatebox{25}{\textsf{\textbf{\textcolor[gray]{0.90}{#1}}}}}}%
%  }%
% }%
}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Textclass specific LaTeX commands.
 \newenvironment{lyxlist}[1]
   {\begin{list}{}
     {\settowidth{\labelwidth}{#1}
      \setlength{\leftmargin}{\labelwidth}
      \addtolength{\leftmargin}{\labelsep}
      \renewcommand{\makelabel}[1]{##1\hfil}}}
   {\end{list}}
 \newenvironment{lyxcode}
   {\begin{list}{}{
     \setlength{\rightmargin}{\leftmargin}
     \setlength{\listparindent}{0pt}% needed for AMS classes
     \raggedright
     \setlength{\itemsep}{0pt}
     \setlength{\parsep}{0pt}
     \normalfont\ttfamily}%
    \item[]}
   {\end{list}}
\hypersetup{
pdftitle = {Modular Software Radio},
pdfauthor = {Linus},
pdfcreator = {DokuTeXit},
pdfproducer = {dokuwiki + TeXit + latex + dvipdf}
}
\title{Modular Software Radio}
\author{Linus}
\dokubackground{http://ipg/}
\begin{document}
\thispagestyle{empty}
\maketitle
\thispagestyle{empty}
\cleardoublepage
\tableofcontents
\newpage
\thispagestyle{plain}
\cleardoublepage
\newpage


 \begin{comment} 


\begin{itemize}
\dokuitem  \hyperref[8800e1c9b3e22c44ba59a34db3fe4841]{Introduction}
\dokuitem  \hyperref[efe79c321127e9bcc1ad7f6956d52ca6]{Architecture}
\dokuitem  Reference-Manuals
\begin{itemize}
\dokuitem  \hyperref[bce059749d61c1c247c303d0118d0d53]{Overview}
\dokuitem  \hyperref[c00425797de3c98e7b32e814b54a6ec5]{GUI}
\dokuitem  \hyperref[3dd8dc66458bf3f59124b3629627bb87]{Signal Processing}
\dokuitem  \hyperref[cd5dbf3629c558b0104ba8f0937d6816]{Makefile}
\dokuitem  \hyperref[158f48c00e990c1d217815f293627562]{DBG-interface}
\dokuitem  \hyperref[4f016ecb0b15468688f1eb81b7a44e50]{Signal Flow}
\dokuitem  \hyperref[6abb51394e80f74c506056160ad1309c]{Important Modules}
\dokuitem  \hyperref[71f7b1ba9fdbe73d19d4343685d7acad]{Subsystem}
\dokuitem  \hyperref[8eb58dd5e328e978169c7b0cbd30d43f]{Interface}
\dokuitem  \hyperref[a5643066c7a784ec29b50db0361ec90f]{FPGA}
\dokuitem  \hyperref[77521cac97140534b4f5eebfd1f61417]{Tidbits}
\end{itemize}

\dokuitem  HOWTOs
\begin{itemize}
\dokuitem  \hyperref[3239be1ec69baea6384eb34ea51a52e3]{From Conception to Measurement} (create module)
\dokuitem  \hyperref[4a931512ce65bdc9ca6808adf92d8783]{Tools}
\dokuitem  \hyperref[59f2da35bcc39525b87932b4cc1f3d68]{Debugging}
\dokuitem  \hyperref[46b862bd16703034ef594b2996ec8166]{Getting Started}
\dokuitem  \hyperref[ae2b1fca515949e5d54fb22b8ed95575]{Testing}
\dokuitem  \hyperref[89d6d3bf5e82fdf45cf1b1c957d612b4]{Using CVS}
\dokuitem  \hyperref[f8c70f328006a690f0b73d80c39289a0]{Creating a simple radio}
\end{itemize}

\dokuitem  Practice
\begin{itemize}
\dokuitem  \hyperref[8800e1c9b3e22c44ba59a34db3fe4841]{Introduction}
\dokuitem  \hyperref[b087a47662fcd995b37ac88f5f4890c2]{Test configurations}
\begin{itemize}
\dokuitem  \hyperref[11648e4e66e7ed6a86cb7f1d0cf604fe]{GPS}
\dokuitem  \hyperref[eecdb28db58d27a3ef51fcc4fa6aecf7]{Radio system}
\dokuitem  \hyperref[1f006088f56c6d16bdde1b8c9c11d62c]{Radar-system}
\dokuitem  \hyperref[548edac4167de2a8b78ee2be17022f7f]{WLAN}
\end{itemize}

\end{itemize}

\dokuitem  \hyperref[9ef73f883d658c9f954cf1213be0313a]{Future thoughts}
\end{itemize}



\begin{itemize}
\dokuitem  \hyperref[6a992d5529f459a44fee58c733255e86]{Index}
\end{itemize}
 \end{comment} 

\part{Introduction}




\dokutitlelevelone{How to read this document}
\label{6a779df1cc3bed9cebdbbd2473172d7b}%% how_to_read_this_document
\label{8800e1c9b3e22c44ba59a34db3fe4841}%%Start: introduction => /var/www/html/ipgwww/data/pages/introduction.txt
Before going into details about what is a software-radio, and what it can be used for, I will give an overview of this document, so that you know where to start first.

This document is separated into six parts:


\begin{itemize}
\dokuitem  Introduction - this is what you're reading right now. It gives some basic definitions and ideas about the signal-processing part as well as the chosen implementation.
\dokuitem  Architecture - here you'll learn more about the design of the different aspects of the software-radio
\dokuitem  Reference Manual - when you need to know about a certain function how to use it or what it does, this is the place to go. Usually you'll need the knowledge from the \dokuitalic{Technical Documents} to know everything.
\dokuitem  How-to - a more practical approach, this could also be called \dokuitalic{tutorial}, as you learn how to use the software-radio step-by-step, without an explanation for the gory details.
\dokuitem  Tipsntricks - a collection of common pitfalls and how to avoid them, plus some help on how to do more unusual things.
\dokuitem  Future Thoughts - lots of things I wanted to do with the software-radio, both technically and experimentally, but that I didn't have any time left. Wanna go for it?
\end{itemize}
At the beginning of each part, you will find a short overview of the different chapters and what they talk about.


\dokutitleleveltwo{Overview of this part}
\label{b84d6670bae704edafc5178c688d3e9e}%% overview_of_this_part

\begin{itemize}
\dokuitem  Motivation - why we want to have a software-radio
\dokuitem  System Overview - the basic building blocks of the software-radio
\dokuitem  Usage - what we are doing with it right now
\dokuitem  Outlook - possible future enhancements
\end{itemize}

\dokutitlelevelone{Motivation}
\label{8b20d3634bbbbf95c71aa00ea43b1dca}%% motivation
This introduction describes our motivation for building a transceiver based on software-radio, hereafter called \dokuitalic{software-radio testbed,} and gives an overview of the general philosophy.


\dokutitleleveltwo{Why Software-Radio?}
\label{dcd09a6cb551e58c90052fa5410f239c}%% why_software-radio
\index{Software-radio!Definition}

\begin{quote}We talk about Software Radio when the map between the data (sending and receiving) 
and the data-carrying antenna signal are completely (within hardware limits) specified by 
the  software. Any map that conforms with the hardware limitations (power, bandwith, hardware 
imperfections) may be implemented by means of an appropriate code. (B. Rimoldi, 2003)\end{quote}


If you like the idea of a flexible transceiver and are not too concerned with size and energy consumption, then you want your transceiver to be software-radio based. For instance, let us say that you have a software radio mobile phone. This mobile phone is a general purpose communication device with a piece of software that makes it behave like a mobile phone. You can turn your mobile phone into a GPS receiver, or a TV receiver, or a Wi-Fi interface, just by down-loading a piece of software (assuming there is a server that has the software you need).

For the technically oriented person: in a software-based transmitter, the software creates the samples corresponding to the signal to be transmitted. A general purpose hardware converts these samples into the signal that will be sent to the antenna. Similarly, in a software-based receiver, the general purpose hardware takes the signal captured by the antenna and produces the corresponding samples. The software does the rest. The hardware is not aware of the standard you are using: it just converts back and forth between samples and waveforms.

Fig.\ref{cap:fig_dumb_hardware} shows the two main components of a software-defined transceiver. The hardware implements a two-way mapping between waveforms and samples. Except for the possibility of controlling the power of the transmitted signal, the amplification of the received signal, as well as some other parameters that are not relevant for this discussion, this mapper performs the same operation regardless of the standard implemented by the transceiver.

\begin{figure}
\begin{center}
img /var/www/html/ipgwww/data/media/dumb{\textunderscore}hardware.ps\end{center}
\caption{\label{cap:fig_dumb_hardware}Dumb hardware and intelligent software}
\end{figure}



\dokutitlelevelone{System Overview}
\label{f3c8a52ac9d2b12d2717f066b1e16768}%% system_overview
\index{Simulation mode!Overview} \index{Real-time mode!Overview} The software-radio helps to make it possible to implement a signal-processing algorithm which works on samples that are transmitted and received over the air.

Because the debugging is an important part of the implementation of a signal-processing algorithm, the software-radio can be run in either \dokuitalic{simulation mode} or in \dokuitalic{real-time mode}. Fig. \ref{fig:simulation_real-time} shows the software-radio in both modes.

\begin{figure}
\begin{center}
img /var/www/html/ipgwww/data/media/simulation{\textunderscore}real-time.ps\end{center}
\caption{\label{fig:simulation_real-time}Structure of the software-radio in both modes}
\end{figure}


\index{Visualize!Overview} The \dokuitalic{Graphical User Interface} (GUI\dokufootnote{Graphical User Interface}) is the only visible part of the software-radio and allows the user to visualize the state of the different \dokuitalic{Modules} as well as to change their configuration. The \dokuitalic{Channel} is a general interface that represents either a \dokuitalic{Simulation} or has access to the \dokuitalic{Hardware}.


\dokutitleleveltwo{Simulation Mode}
\label{df49fe7d89a49ace7d2375f95e06980f}%% simulation_mode
In simulation mode no hardware is used, and the whole transmission is simulated in software, including Gaussian noise and multi-path fading. There are no real-time constraints which makes it very easy to debug the algorithm to be implemented.

Of course, if you don't have access to the right hardware, this is the only possibility to use the software-radio. However, the \dokuitalic{channel-server} which links multiple channels together, is written to simulate a real channel with high enough accuracy to test and verify signal-processing algorithms.


\dokutitleleveltwo{Real-Time Mode}
\label{9f952a4ca291eb6081e306e3b3505666}%% real-time_mode
In real-time mode only the Graphical User Interface runs on Linux, while the rest of the software-radio runs in Real-Time mode, made available through the use of RTLinux. This is necessary, as the transmission and reception of the samples has to meet time-constraints that are not possible to meet in simple Linux.

As of spring 2004, there exists two hardware-platform that allow the software-radio to do actual transception of samples over the air. The older one, produced by STMicroelectronics, offers a simple SISO-interface, that is, one antenna at each end of the transmission. The newer interface, produced by ICS-Ltd, allows the software-radio to take advantage of a MIMO-channel, with up to four antennas at each end of a transmission. A MIMO-channel is defined as a channel that has more than one transmitting antenna and more than one receiving antenna. These channels have very interesting properties, mainly the possibility to multiply the available channel-capacity by a function of the available antennas.


\dokutitleleveltwo{Communication}
\label{979b93285de87c4731fc824bd9e4ba75}%% communication
\index{Channel-server!Overview} The software-radio is built to have a two-way communication. So, if you have more than one instance of a software-radio running, they can communicate together.

If the software-radio is run in real-time mode, only one instance of a software-radio can run on a computer. So if you want to communicate in real-time, you need at least two computers.

In simulation mode, the number of instances per computer is only limited by its calculation-power (and the patience of the user ;). A \dokuitalic{Channel-Server} connects all channels of all instances of the software-radio together and makes it possible that everybody can listen to what the other radios are sending.


\dokutitlelevelone{Usage}
\label{9366282e11c151558bdfaab4a264aa1b}%% usage
\label{chap:Usage} At EPFL, the Federal Institute of Technology in Lausanne, Switzerland, we use the software-radio both in class and for research purposes.

This chapter gives an overview of what we did with the software-radio until the end of 2003, what we are doing now in winter/spring 2004, and what we are planning to do during the rest of this year.


\dokutitleleveltwo{Past}
\label{68e2d83709f317938b51e53f7552ed04}%% past
 In class, it has been used to demonstrate the different parts of a radio-transmission, such as modulation, spreading, coding and matched filtering.

 For research, we used it succesfully to demonstrate the usability of LDPC-codes over the air and to verify their theoretical performance.


\dokutitleleveltwo{Present}
\label{47ed49958e2500d72e305f85ed316c91}%% present
 We are looking in the challenges arising from MIMO transmission that is coded with LDPC-codes. There are timing constraints to be solved, as well as theoretical challenges with regard to the MIMO channel to be met. 


\dokutitleleveltwo{Future}
\label{da907a1b8f74e6922d93b025eecfb852}%% future
 Different projects for the software-radio are in preparation. These include a better matched filter (channel estimation), ZigBee implementation and the obligatory GPS-decoder. 


\dokutitlelevelone{Outlook}
\label{cd0fbb7849b9b9d84c4f8e48e7301ecf}%% outlook
 For the time being, the software-radio is taking a direction towards point-to-point communications in MIMO-channels. We would very much like to study the implications of multi-point to multi-point communications, as well as low-tech implementations of a communication.


\dokutitleleveltwo{Multi-point to Multi-point}
\label{06f2eede80229074ef29cf30755ca82f}%% multi-point_to_multi-point
 Point-to-point communications are quite well known. In fact, every commercially available transmission technology today only works in a point-to-point configuration, usually surrounded with a method to be sure that only one person is sending at the same time on the same frequency.

 Different theories describe the possiblity of having more than one sender at the same time and being able to reconstruct the signal at the other end. It would be very interesting to study these theories in a real environment in order to give a feed-back about problems arising when implementing such theories.


\dokutitleleveltwo{Low-Tech Communication}
\label{7792bee59b0703f16a07f88d3391af9e}%% low-tech_communication
 The current hardware in use is capable taking advantage of several MHz\dokufootnote{Megahertz} of spectrum to transmit and receive. HAM-radios only have a couple of kHz of spectrum available for the transcpetion. It would be interesting to study transmission using a sound-card and a HAM-radio, perhaps to propose a better and faster transmission than AX.25. 

\part{Architecture}




\dokutitlelevelone{Overview}
\label{bce059749d61c1c247c303d0118d0d53}%% overview
\label{efe79c321127e9bcc1ad7f6956d52ca6}%%Start: architecture => /var/www/html/ipgwww/data/pages/architecture.txt
In this part you'll learn about the architecture behind the software-radio. If you're looking for a precise information, you may be better off by looking at the \dokuitalic{reference}-part of this document.

\begin{figure}
\begin{center}
img /var/www/html/ipgwww/data/media/architecture{\textunderscore}overview.ps\end{center}
\caption{\label{fig:architecture_overview}The three main components and their respective subdivisions}
\end{figure}


We like to split the software-radio in three parts: GUI\dokufootnote{Graphical User Interface}, Signal Processing and the Antenna, as can be seen in figure \ref{fig:architecture_overview}. For each of these elements, you can find a chapter that describes it in more detail. Additionally to these aspects, there are more general ones that don't fit that nicely into the pictures. Here is an overview of the chapters in this part of the documentation: 


\begin{itemize}
\dokuitem  GUI\dokufootmark{1} Is the Graphical User Interface, that allows to interact with the software-radio on a user-level
\dokuitem  Signal Processing is the ensemble of all interchangeable participants that make the active part of the software-radio
\dokuitem  Antenna represents the transmission and reception part of the software-radio, either in simulation or in real-time mode
\dokuitem  Operating system how the different parts of RTLinux and linux play together
\dokuitem  Modes of Operation gives an overview of the different modes of the software-radio
\dokuitem  Hardware which shows the architecture of the ICS-hardware
\dokuitem  Code the different directories in the tar-ball of the software-radio
\end{itemize}

\dokutitlelevelone{GUI}
\label{c00425797de3c98e7b32e814b54a6ec5}%% gui
\index{Visualize!Architecture|(} For taking measurements and changing the behaviour of the software-radio we developed this Graphical User Interface, called \dokuitalic{Visualize}. It is capable of showing the internal states of all active modules (parts of the software-radio), their signals and changing the configuration of these modules while the software-radio is running.

By looking at figure \ref{fig:architecture_overview}, we distinguish three main-parts of the GUI\dokufootnote{Graphical User Interface}:


\begin{itemize}
\dokuitem  User I/O is the input and output towards the user. It shows the chains, updates the statistics and offers windows to configure the modules
\dokuitem  Mapper arranges the modules in the software-radio to chains
\dokuitem  FifoCmd interfaces with the software-radio
\end{itemize}

\dokutitleleveltwo{User I/O}
\label{c5029b90049f86206e35875bafafef2a}%% user_i_o
\index{Visualize!User I/O} Different ways of interfacing the software-radio exist. The user can display:


\begin{itemize}
\dokuitem  Chains which is an overview of the general state of the software-radio
\dokuitem  Stats representing internal values of the modules, single values or plots
\dokuitem  Output-ports that are the signals that pass from one module to the next
\dokuitem  Plots tracing stats of different modules against each other or in time
\end{itemize}
There exist two ways of actively interacting with the software-radio:


\begin{itemize}
\dokuitem  Re-configuration by changing parameters of one or more modules
\dokuitem  Process Data which informs a module to immediately do something by processing it's input
\end{itemize}

\dokutitleleveltree{Chains}
\label{99469f92ab96d54efce3d605a4bb4fbe}%% chains
When the \dokuitalic{Visualize}-tool is started, it displays an overview of all active chains for the first antenna of the first radio it finds. In fig. @screenshot of visualize start-up@ you see the STFA in the middle, surrounded by a sending and a receiving chain. Each module in the chain has its name displayed, as well as up to two parameters of its internal state.


\dokutitleleveltree{Stats}
\label{446501053769c06c565094b26d26e8ef}%% stats
A stats can either be a single value or a \dokuitalic{block} of values. Examples of single values include SNR, variance, BER or counters, while \dokuitalic{blocks} of values can include channel-vectors, slots or a whole frame. 


\dokutitleleveltree{Output-ports}
\label{abb9ae0554141d2b78420ed9c9ea25da}%% output-ports
Each module has zero to many output-ports that can be displayed in a seperate window. As these signals can be of complex nature, one can chose to display only the real, only the imaginary, or the absolute part. Additionally, one can chose to display the FFT of the first $2^{\lfloor log_2 \rfloor}$
 samples of the signal. 


\dokutitleleveltree{Plots}
\label{73c9533e16d5d54e71b2eb35012edb86}%% plots
You may also be interested in a plot of one stats-variable in time or of two stats-variables one against the other. The \dokuitalic{Visualize}-tool opens each new plot in a seperate window. 


\dokutitleleveltree{Export}
\label{b2507468f95156358fa490fd543ad2f0}%% export
All plotting-windows can be exported either as postscript-file or as a Matlab-function (which are also compatible with Octave). 


\dokutitleleveltree{Re-configuration}
\label{b31ea6439bb7efc170ebb8601929cecd}%% re-configuration
When asking for a re-configuration window, the \dokuitalic{Visualize}-tool will update the software-radio with every new value you fill in. This is very useful for educational and debugging purposes. 


\dokutitleleveltree{Process-Data}
\label{b8c1e21de5c9537b408d5898a4563738}%% process-data
This is mainly a debugging-function and allows to send a \dokuitalic{Data-msg} to one of the modules, which will then process whatever is in its input. 


\dokutitleleveltwo{Mapper}
\label{4b9f83e1257a95912768124924dfb143}%% mapper
\index{Visualize!Mapper} This is an important part of the \dokuitalic{Visualize}-tool, as it's not a straightforward task to identify chains and display them correctly. It is basically the original version written by two 4th year students, but extended to work with more than one STFA, or other main-modules. 


\dokutitleleveltwo{FifoCmd}
\label{89a03a7e1e0197f7dcad08fc6f255c0e}%% fifocmd
\index{Visualize!FifoCmd} This is the interface to the software-radio and takes care about the communication between the two. Everything is driven by the \dokuitalic{Visualize}-tool, which means that the software-radio does only reply to requests from the GUI\dokufootmark{1} and never initiates a request by itself. \index{Visualize!Architecture|)} 


\dokutitlelevelone{Signal Processing}
\label{3dd8dc66458bf3f59124b3629627bb87}%% signal_processing
\index{Signal Processing!Architecture|(} Our goal was to find a suitable tradeoff between code re-use and performance of the software-radio. This is why we chose to have a modular framework, running on a RTLinux-platform. In the following sections, you will learn about the following items:


\begin{itemize}
\dokuitem  DBG the interface to the GUI\dokufootnote{Graphical User Interface}
\dokuitem  Framework which makes it possible that modules can interact with each other and the outer world
\dokuitem  STFA the interface to the channel
\end{itemize}

\dokutitleleveltwo{DBG}
\label{b1da4861a4edf5615ec39f07963ea8db}%% dbg
\index{Signal Processing!DBG} The debug-interface allows the user to interact with the software-radio. It accepts commands and queries from the GUI\dokufootmark{1}\dokufootnote{the FifoCmd class
encapsulates all queries and commands} and replies accordingly. Looking at figure \ref{fig:architecture_dbg} you can see the Fifos used in both RF- and simulation-mode.

\begin{figure}
\begin{center}
img /var/www/html/ipgwww/data/media/architecture{\textunderscore}dbg.ps\end{center}
\caption{\label{fig:architecture_dbg}The debug-interface in RF- and simulation-mode}
\end{figure}


The replies of the dbg-module can be either status-informations or data directly from the software-radio. An overview of the different queries/replies can be found in \ref{chap:dbg-interface}.


\dokutitleleveltwo{Framework}
\label{756457dc85f13450b3dfba2cbc1465e5}%% framework
\index{Signal Processing!Framework|(} \label{sec:framework} The modules, which define the specific task of the software-radio, are surrounded by a framework that takes care of the book-keeping tasks necessary to guarantee a good working together of the different modules.

There are three parts:


\begin{itemize}
\dokuitem  Modules and Chains the specific description of different signal-processing parts, like pulse-shape filter, coding, mapping, and others
\dokuitem  CDB Class Data Base, where a reference to every available module is stored
\dokuitem  SDB Subsystem Data Base, which contains a reference to every instantiated and thus active module, as well as the glue that makes it work
\end{itemize}
Because of the complexity of the subsystem alone, it has its own subsection where an overview of its capabilities is shown. The same goes for the STFA.


\dokutitleleveltree{Modules and Chains}
\label{1436fbe1dca2efa12d4bc6e279a7b8ad}%% modules_and_chains
\index{Signal Processing!Modules and Chains} \label{subsec:modules and chains} The communication system is built out of modules. Each of the modules has a classroom-style function. As an example, in a simple one-way communication system, the transmitter could consist of a first module that maps bits into signal space points and a second module that maps signal space points into samples. In the corresponding receiver you may find a module that implements the matched filter, and another module that decides what was transmitted.

Signal processing modules have inputs and outputs for the signals being processed. They also have a configuration-part to control the behavior of the module (e.g. the desired amplification for an amplifier) and statistics to display relevant information (e.g. internal variables). This is shown in fig. \ref{cap:Two-simple-chains}.

\begin{figure}
\begin{center}
img /var/www/html/ipgwww/data/media/modular.ps\end{center}
\caption{\label{cap:Two-simple-chains}Two simple chains and a module in detail}
\end{figure}


Each of the modules can exist in multiple copies. The framework (composed of CDB and SDB) makes sure that each copy can work independently of the other copies, not unlike the class/instance-behaviour of C++ or other object-oriented languages.

When one or more modules are linked together, we speak about a \dokuitalic{chain} of modules. The software-radio knows how to pass the data from one module to another, and will call each module at the appropriate time, that is when it has some data to process.


\dokutitleleveltree{CDB and SDB}
\label{376e92a3d526db883e91c0aabae5ca8f}%% cdb_and_sdb
\label{subsec:cdb} \label{subsec:sdb} \label{subsec:cdb and sdb} \index{Signal Processing!CDB} \index{Signal Processing!SDB} \index{CDB!Architecture} \index{SDB!Architecture} The Class Data Base (CDB) and Subsystem Data Base (SDB) make it possible to use the modules in an object-oriented approach. While the CDB holds the static information about a module, such as the names and types of the configuration-parameters, the SDB holds an actual implementation of a module, with the specific configuration-values that may differ from one implementation to another.

\begin{figure}
\begin{center}
img /var/www/html/ipgwww/data/media/cdb{\textunderscore}sdb.ps\end{center}
\caption{\label{fig:cdb_sdb}The CDB and SDB}
\end{figure}


An overview of the CDB and SDB can be found in fig. \ref{fig:cdb_sdb}. It shows part of a running software-radio that has two transmitting and two receiving slots\dokufootnote{For clarity, only part of the chains are shown}. On the left side you see the CDB that holds a description of each module that has been loaded in the software-radio. On the right-hand side, you see the actual instantiations of some modules present in the CDB.

The loading of the modules happens usually at start-up, but theoreticaly it's also possible to load further modules once the software-radio has been started. While loading, a module informs the CDB about it's presence, and includes the input/output signal-types, it's name, configuration and statistics-names and -types. After that, the module is inscribed in the CDB, but not yet not active.

Once a module is needed in the software-radio, it is \dokuitalic{instantiated}, that is, a running instance of the module is created. This includes reservation of memory needed for the different variable parts, as well as initialisation of these parts. After a module is instantiated, it can be connected to other modules and can perform signal processing.


\dokutitleleveltree{Subsystem}
\label{71f7b1ba9fdbe73d19d4343685d7acad}%% subsystem
\label{sub:spc_subsystem} \index{Signal Processing!Subsystem} Usually the subsystem is a part of the SDB. But over time it has become quite complex and would deserve an own directory in the Base/-directory \dokufootnote{Future work hint\ldots{}}. One can think of the subsytem as the base-class for all modules. It offers a handful of virtual functions that allow it to interact with the modules.

 The main goal of the subsystem is to allow interaction between two modules. In figure \ref{fig:architecture_subsystem} all the possible interactions between two modules are shown.

\begin{figure}
\begin{center}
img /var/www/html/ipgwww/data/media/architecture{\textunderscore}subsystem.ps\end{center}
\caption{\label{fig:architecture_subsystem}Two modules and all possible connections}
\end{figure}


It is thus responsible for the following tasks:


\begin{itemize}
\dokuitem  Allocating Memory for the Data, Config- and Stats-blocks
\dokuitem  Messaging between modules and do most tasks
\dokuitem  Threading the modules if necessary
\end{itemize}
 Most changes in the state of a module include a message sent to the attached modules. An overview and short description of every message can be found in \ref{sec:sp_subsystem}.


\dokutitleleveltree{STFA}
\label{adebc2516025b7bd604b0cfcfa740885}%% stfa
\label{subsec:stfa} \index{Signal Processing!STFA} The Slot To Frame Allocator (STFA) is a module that makes the connection between the antenna and the rest of the modules. It offers a frame-based, slotted TDD interface to the rest of the signal-processing modules.

There exist two STFAs, one for the old hardware and one for the new, ICS-based hardware. The first is called stfa, while the second is called stfa{\textunderscore}ics. \index{Signal Processing!Framework|)} \index{Signal Processing!Architecture|)}


\dokutitlelevelone{Antenna}
\label{f212100e38f782e152ebfab712a0e6ec}%% antenna
\index{Antenna!Architecture|(} The antenna-part of the software-radio has the structure as shown in fig. @Antenna-blowup: Common/Driver/HW/Server@ Their respective functions are as follows:


\begin{itemize}
\dokuitem  Common is the interface towards the signal processing part
\dokuitem  Driver implements a certain hardware or simulation
\dokuitem  Hardware or Simulation the actual transmission system
\end{itemize}

\dokutitleleveltwo{Common}
\label{9efab2399c7c560b34de477b9aa0a465}%% common
\index{Antenna!Common} The interface of the antenna offers the following parameters to the signal-processing part:


\begin{itemize}
\dokuitem  DMA-region a place where the received samples are written to and the samples to be sent are read from
\dokuitem  RF-parameters frequency, amplitude and other config-parameters
\dokuitem  Timing an function is available that tells about the actual timing of the RX/TX part
\end{itemize}

\dokutitleleveltwo{Driver}
\label{e2d45d57c7e2941b65c6ccd64af4223e}%% driver
\index{Antenna!Driver} This is the implementation of a certain way to transmit and receive samples. It has to take care about all initialisations and correct handling of all exceptions. The following drivers are functional:


\begin{itemize}
\dokuitem  RF interfaces the old, STMicroelectronics based RF-system
\dokuitem  ICS interfaces the new, ICS-based RF-system that is capable of MIMO-transmission
\dokuitem  Simul for simulations of the RF-system
\dokuitem  Simul{\textunderscore}ics for simulations of the ICS-system
\dokuitem  Emul does a simple copy of the data to be transmitted to the next slot
\dokuitem  NOP does nothing, for debugging purposes
\end{itemize}

\dokutitleleveltwo{Hardware or Simulation}
\label{7d77d08d37d2fbaad55c37e7ba41198f}%% hardware_or_simulation
\label{sec:HWorSimul} The final part of the software-radio defines the channel. The \dokuitalic{Emul} driver, for example, implements a flat single-tap channel with no noise. The \dokuitalic{Simul} drivers need a channel-server that takes multiple radios together, mixes their signal, and sends back the calculated signal.

The most interesting parts are the RF and ICS hardware, because they offer a real channel to test the transmission with.


\dokutitleleveltree{Hardware}
\label{3ca14c518d1bf901acc339e7c9cd6d7f}%% hardware
\index{Antenna!Hardware} In the following table you can find a comparison of the two hardware-systems available. \begin{center}

%% Table analyse:
%%    Numrows: 5
%%    Most Long row size: 43
%%    Choose table mode: tabular
\begin{figure}[h]
\begin{tabular}{lll}
\hline
\multicolumn{1}{|r|}{  }&\multicolumn{1}{l|}{ RF }&\multicolumn{1}{l|}{ ICS }\\ 
\hline
\multicolumn{1}{|l|}{ Max. number of antennas }&\multicolumn{1}{l|}{ 1 }&\multicolumn{1}{l|}{ 4 }\\ 
\hline
\multicolumn{1}{|l|}{ Frequency [GHz\dokufootnote{Gigahertz}] }&\multicolumn{1}{l|}{ 1.9 }&\multicolumn{1}{l|}{ 2.4-2.48 }\\ 
\hline
\multicolumn{1}{|l|}{ Bandwith [MHz\dokufootnote{Megahertz}] }&\multicolumn{1}{l|}{ 3.8 }&\multicolumn{1}{l|}{ 1 }\\ 
\hline
\multicolumn{1}{|l|}{ Resolution }&\multicolumn{1}{l|}{ 12 }&\multicolumn{1}{l|}{ 14 }\\ 
\hline
\end{tabular}
\end{figure}

\end{center}


\dokutitleleveltree{Simulation}
\label{9e083ec666c9f3db044bb7c381640227}%% simulation
\index{Antenna!Simulation} In simulation-mode, a channel-server accepts connections from different radios, as can be seen in fig. @channel-server with two radios@. The channel-server can simulate multi-tap channels and add gaussian noise to the transmitted signals. This allows for easy simulation of real-world signals, before taking the modules on the air. \index{Antenna!Architecture|)}


\dokutitlelevelone{Operating System}
\label{c1648d725751579ba44aa410b349e8e4}%% operating_system
\index{Operation System} One very important aspect of a software-radio is it's real-time capability. In our implementation, we transmit and receive slots of a duration of about 1ms. If we want to make sure that there is no blank in the transmission, we need to make sure to do our calculations in this short time-span and to do it at the right moment.

 In a modern operation system, lots of things are happening at the same time: graphics, sound, network, disk-access and more. A normal program will have to wait for these tasks to finish, before it can do it's work. This means that it's nearly impossible for a normal program to meet sub-ms precision. Different approaches exist to bring a solution to this problem. We chose RTLinux because of it's stability, availability and because it is licensed under the GPL\dokufootnote{GNU General Public License} which means that other people can use this solution without having to pay high software-costs.

 In short, RTLinux allows to meet time-constraints of a couple of $\mu s$
, the precision-constraint that is given by todays hardware. It does this by running a real-time aware micro-kernel which is principally responsible for scheduling. One of the default tasks that runs with the lowest priority is the linux-kernel. This makes sure that even if the kernel is busy doing one of the not-so important things, RTLinux may put it to sleep, execute the real-time task, and resume the linux-kernel.


\dokutitlelevelone{Modes of Operation}
\label{d75778e88e6aa01545b25c92a8f0ebea}%% modes_of_operation
\index{Modes of Operation|(} \label{cha:modes of operation} As the signal-processing part and the framework is very flexible, different operating-modes are possible:


\begin{itemize}
\dokuitem  Test which includes just a simple chain that is run a limited number of times
\dokuitem  Simulation or Real-Time modes which are possible for both Local-Loop and the Two-Radio System
\dokuitem  Local-Loop where a radio 'talks' to itself by receiving every sample sent
\dokuitem  Two-Radio System a set of two radio, where each one talks to the other
\end{itemize}
In the following sections, the advantages of each of these are listed.


\dokutitleleveltwo{Test}
\label{098f6bcd4621d373cade4e832627b4f6}%% test
\index{Modes of Operation!Test}  As the name indicates, this is used to test the basic functionality of a module. Usually it includes a simple chain that has only the most basic components in it in order to test the module. Like this one can test the module in a simple environment, before going through the more real and more complete test in a real-time communication.

 To test a mapper-module that maps bits into complex symbols, it would be enough to have the chain as depicted in fig. @show modules: source{$\rightarrow$}mapper{$\rightarrow$}block{$\rightarrow$}slicer{$\rightarrow$}sink@ For convenience, the \dokuitalic{source} can contain readable text-messages that are printed by the \dokuitalic{sink} and can be verified by hand.

 The \dokuitalic{block} module exists in different variants, where MIMO channels and multi-tap fading channels can be simulated, both in a convenient, deterministic manner.


\dokutitleleveltwo{Simulation or Real-Time}
\label{f6a9efbf66671e531cc1c58c120c1ab2}%% simulation_or_real-time
\index{Modes of Operation!Simulation or Real-Time} As already described in section \ref{sec:HWorSimul}, the software-radio can be run either locally without the RF-hardware and in a user-space mode, or it can be run in real-time using special RF-hardware for transmission and reception. While the former is much more easy to debug, only the latter allows to make real-world measurements and confirmation of theoretical results.

In the software-radio, both modes are transparent to the user, as the decision between the simulation or the real-time mode only has to be taken when running it. For the user, in either case, the channel is represented by the STFA.


\dokutitleleveltwo{Local-Loop}
\label{d7c58173a22a083ee38f0597e8b4e246}%% local-loop
\index{Modes of Operation!Local-Loop} Sometimes it is too complicated to take care about all the synchronisation and fading-problems. Then you can chose to run your modules to test in a local-loop, and thus always be synchronised.  When running in simulation-mode, the channel-server makes sure that the sent samples are received at the same time. If you run the radio in real-time mode, then you have to make sure to connect the output of the cards with the input through a cable.


\dokutitleleveltwo{Two-Radio System}
\label{e39066cb8bdc9214fbd222d9640d1198}%% two-radio_system
\index{Modes of Operation!Two-Radio System} \index{Two-Radio System} TODO: update for ICS-example

This section describes a basic system with two radios, following the example of the radio found in \dokuitalic{Radios/Simple/BS} and \dokuitalic{Radios/Simple/MS\dokufootnote{Microsoft}}. It is important to know about this if you want to do more than just run the examples. You will learn about the most important modules, how to put them together and what make the thing going.


\dokutitleleveltree{Setup}
\label{a0f848942ce863cf53c0fa6cc684007d}%% setup
\index{Two-Radio System!Setup}

\begin{figure}
\begin{center}
img /var/www/html/ipgwww/data/media/simple{\textunderscore}setup.ps\end{center}
\caption{\label{cap:The-most-simple}The most simple two-way communication example}
\end{figure}


Looking at fig. \ref{cap:The-most-simple}, you can see two parts: a master and a client \dokufootnote{Historically, the master is called BS (for BaseStation) and the client is called MS\dokufootmark{1} (for MobileStation).}.  The communication channel in this example consists of three slots, of which only two are occupied \dokufootnote{There are three slots in order to allow for a more relaxed timing.}. The part in the middle, where the tree slots reside, is called STFA, which means Slot To Frame Allocation. This is the most basic module that you will find in mostly all of the software-radio. The input of the STFA are sent through the antenna, while the received signal from the antenna is passed through the output of the STFA. As you can see in figure \ref{fig:architecture_overview}, the antenna is a placeholder for either a real channel or just a simulation.


\dokutitleleveltree{Modules}
\label{0eb9b3af2e4a00837a1b1a854c9ea18c}%% modules
\index{Two-Radio System!Modules} This is a short overview of the different modules: 
\begin{lyxlist}{00.00.0000}

\item [sch{\textunderscore}send]Synchronisation CHannel. This module generates data that is used to communicate the configuration of the other clients. This includes the configuration about which slot to use for sending, which slot to use for receiving, and gain-control. Most of it is not used in a two-radio case.


\item [modulator]Takes bits as inputs and creates complex symbols. In its default-configuration, it outputs QPSK symbols.


\item [spread]Spreads the input-symbols with a given sequence. Usually this is used to have more than one radio sending during the same slot, in this example it is used to give some protection to the data, as a spreader may act as a simple coder.


\item [chest{\textunderscore}send]Inserts a training-sequence into the signal. This sequence is known at the receiver-end, which uses it then to estimate the channel and to create the matched-filter.


\item [synch{\textunderscore}send]Adds a synchronisation-sequence to the signal. The sequence is done in a special way so as to make it possible to retrieve the synchronisation-signal with as less calculation as possible.


\item [rrc]The Root Raised Cosine pulse-shape filter. Takes the complex signal, upsamples by a factor of two and generates a real output.


\item [stfa]Slot To Frame Allocation, takes the slots and prepares them to be sent over the channel.


\item [rrc{\textunderscore}rcv] Applies again a Root Raised Cosine filter


\item [chest{\textunderscore}rcv]The counterpart to \dokuitalic{chest{\textunderscore}send}, calculates the channel-estimation and the matched-filter, and applies it to the input-signal.


\item [demodulator]Makes a hard decision on the received signals.


\item [sink]Prints to the screen the received sequence of bits.


\item [synch{\textunderscore}rcv]Keeps up the synchronisation with the master.


\item [despread]Undos the operation introduced by the spreader, and offers a cleaner signal. As coding module this is suboptimal.


\item [sch{\textunderscore}rcv]Decodes the synchronisation-channel and sets the tx-amplitude according to it's information.

\end{lyxlist} 


\dokutitleleveltree{Master}
\label{eb0a191797624dd3a48fa681d3061212}%% master
\index{Two-Radio System!Master} The masters task is to send out the synchronisation-signal on it's slot 1, combined with the data-signal that tells an eventual client its required tx-gain. The tx-gain of the client is calculated with the power received on slot 2. If it is below a certain threshold, the master considers that no client is sending, and puts the tx-power to 0. If the receiving-power is above a certain threshold, the tx-gain is adjusted to what the master would like to hear. This task in fact is done automatically by the sch{\textunderscore}send module. 


\dokutitleleveltree{Client}
\label{62608e08adc29a8d6dbc9754e659f125}%% client
\index{Two-Radio System!Client} While the master is quite static, the client has to do lots more:


\begin{enumerate}\dokuitem  Search for the synchronisation-signal
\dokuitem  Set up the synch-slot and uplink-slot
\dokuitem  Keep the synchronisation
\end{enumerate}
The first point is necessary because the client doesn't know beforehand the time-frame of the master. So, in order to get it, the mobile sets up a \dokuitalic{synch{\textunderscore}rcv} module on each slot, and choses the one that has the highest probability of a successful synchronisation. After this, it updates the offset of the STFA, so that it is in synch with the master, and keeps one \dokuitalic{synch{\textunderscore}rcv} module active, to allow for further synchronisation. All this is done in a macro-module called \dokuitalic{macro{\textunderscore}synch}.

Once the primary synchronisation is achieved, it will set up some modules to decode and demodulate the synchronisation-channel, as well as set up a tx-channel on slot 2.

After this it has to keep up the synchronisation, because the master and the client don't have exactly synchronised clocks. \index{Modes of Operation|)}


\dokutitlelevelone{Hardware}
\label{3ca14c518d1bf901acc339e7c9cd6d7f}%% hardware
\index{Hardware!Architecture} The current hardware is composed of three parts, as can be seen in fig. @figure of layout with ICS-rx and tx, as well as RF-cards@ This setup is optimized towards a 4{\texttimes}4 MIMO-system at 2.4GHz.


\dokutitlelevelone{Code}
\label{c13367945d5d4c91047b3b50234aa7ab}%% code
\index{Code!Architecture} Once you untar the SRadio-*.tar.gz file, you find a directory in the form of \dokuitalic{SRadio-1.0.0}\dokufootnote{the name has to start with SRadio, or else
the Makefiles won't work!} under which all the code is placed.


\dokutitleleveltwo{Directory Structure}
\label{b52eaaed97f7ab6022d5b0c4f637d2e4}%% directory_structure
\label{sub:Directory-structure} 
\begin{lyxlist}{00.00.0000}

\item [Base]CDB, SDB and the channel implementations are found here, as well as some general helping functions to the MSR.


\item [Conventions]template files that can be copied to new projects and then be filled in


\item [Modules]all user-written modules are found in here, put into different categories: Coding, Channel, Data, General, Macro, Signal


\item [Test]simple chains that are used to test the basic functionalities of the modules


\item [Radios]full-fledged two way transmission parts


\item [User]place for all compiled user-libraries


\item [Kernel]place for all compiled kernel-libraries


\item [Documentation]where you find this manual as well as some presentations

\end{lyxlist} 

\part{Reference-Manuals}




\dokutitlelevelone{Overview}
\label{bce059749d61c1c247c303d0118d0d53}%% overview
\label{bce059749d61c1c247c303d0118d0d53}%%Start: overview => /var/www/html/ipgwww/data/pages/overview.txt
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}
\dokuitem  GUI\dokufootnote{Graphical User Interface} shows an overview of the classes used in the \dokuitalic{Visualize} program
\dokuitem  Signal Processing gives more details about the CDB and SDB, as well as the subsystem and the modules
\dokuitem  Antenna what a driver has to implement in order to be used
\dokuitem  Hardware how to set up the hardware
\dokuitem  Modules a detailed description of the most often used modules
\end{itemize}



\dokutitlelevelone{GUI}
\label{c00425797de3c98e7b32e814b54a6ec5}%% gui
\label{c00425797de3c98e7b32e814b54a6ec5}%%Start: gui => /var/www/html/ipgwww/data/pages/gui.txt
\index{Visualize!Reference|(}

The Graphical User Interface for the software-radio is called \dokuitalic{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.


\dokutitleleveltwo{General Interface}
\label{035d2a507c3c14ef83791edf0aad8b14}%% 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}
\begin{center}
\includegraphics{/var/www/html/ipgwww/lib/plugins/tmp/texitimages/texitir3POm.ps}\end{center}
\caption{\label{fig:visualize_interface}The classes involved in bringing up the main view}
\end{figure}


\index{Visualize!Classes!Interface} There is one main-window, even if there are multiple radios to display. The main window, created by \dokuitalic{Interface}, contains a \dokuitalic{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 \dokuitalic{RadioView} module which is the active \dokuitalic{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 \dokuitalic{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 \dokuitalic{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 \dokuitalic{CanvasView}, which is subclassed from \dokuitalic{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 \dokuitalic{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 \dokufootnote{Here is a possibility to rewrite a class}. The main-module is called \dokuitalic{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 \dokuitalic{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\dokufootnote{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.


\dokutitleleveltwo{Interaction}
\label{579fe8571f2ee2236549c849e11251fa}%% interaction
There are a number of ways the user can interact with the GUI\dokufootnote{Graphical User Interface}:


\begin{itemize}
\dokuitem  Chosing the stats to be displayed on the module
\dokuitem  Showing a stats-graphic
\dokuitem  Showing a graphic of an output-port
\dokuitem  Configuring values of a module
\dokuitem  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}
\dokuitem  Interface is the head of the visualize-tool and is the only one to have access to the menus
\dokuitem  Module represents a software-radio module
\dokuitem  Block is the virtual class for the (output)port, stats and plot
\dokuitem  Port knows how to read data from an output-port
\dokuitem  Stats reads a stats-'block' that represents some data
\dokuitem  Plot has a flexible data-part that can grow over time
\dokuitem  ConfWind shows a window with all configuration-options of the module
\dokuitem  Image is a special stats-'block' representing an image
\dokuitem  Show allows a Block to be displayed, complete with all control-widgets necessary
\dokuitem  PlotWin takes care of chosing the stats to be displayed
\end{itemize}
 \begin{figure}
\begin{center}
\includegraphics{/var/www/html/ipgwww/lib/plugins/tmp/texitimages/texitd3xjFV.ps}\end{center}
\caption{\label{fig:visualize_display}The different display-options}
\end{figure}



\dokutitleleveltree{Plotting}
\label{1e35c0e87b1f2aa1346b44c7cf010c31}%% 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 \dokuitalic{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.


\dokutitleleveltree{Configuration}
\label{ccd1066343c95877b75b79d47c36bebe}%% configuration
\index{Visualize!Classes!ConfWind} If the user requests a reconfiguration of a module, a \dokuitalic{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.


\dokutitleleveltree{Signal and Outputs}
\label{94c6b2594c843d6e353493cbaa114119}%% signal_and_outputs
\index{Visualize!Classes!Show} Both require the Module to instantiate a \dokuitalic{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.


\dokutitleleveltree{Image}
\label{78805a221a988e79ef3f42d7c5bfd418}%% image
\index{Visualize!Classes!Image} Althogh \dokuitalic{Image} is a stats-variable, it is implemented as a class on its own\dokufootnote{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.


\dokutitleleveltwo{Internal}
\label{d1efad72dc5b17dc66a46767c32fff40}%% internal
These classes deserve some more specific treatement.


\dokutitleleveltree{Mapper}
\label{4b9f83e1257a95912768124924dfb143}%% 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 \dokuitalic{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.


\dokutitleleveltree{FifoCmd}
\label{89a03a7e1e0197f7dcad08fc6f255c0e}%% fifocmd
\label{sec: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.


\dokutitleleveltree{Module}
\label{22884db148f0ffb0d830ba431102b0b5}%% module
 \index{Visualize!Classes!Module} Together with the Mapper, this is one of the main classes. Its tasks consist of:


\begin{itemize}
\dokuitem  Draw itself on the canvas with the name and the chosen stats-parameters, including the pads for the connections and eventual performance-measurements
\dokuitem  Show windows for output- and stats-signals, as well as configuration
\dokuitem  Process some data of the module. This is mostly useful in debugging-mode and for test-cases. It corresponds to a \dokuitalic{call{\textunderscore}module} in the software-radio.
\end{itemize}
\index{Visualize!Reference|)}




\dokutitlelevelone{Signal Processing}
\label{3dd8dc66458bf3f59124b3629627bb87}%% signal_processing
\label{3dd8dc66458bf3f59124b3629627bb87}%%Start: signal_processing => /var/www/html/ipgwww/data/pages/signal_processing.txt

\dokutitleleveltwo{CDB}
\label{785b30443fd6e2de160408ddcfcae6fa}%% cdb
\index{CDB!Reference|(} There are two classes of functions in the CDB: defining a module and requesting informations about defined modules. While the latter is only used internally of the software-radio, the former is also used in the module-definition. Both type of functions are also described briefly in \dokuitalic{Include/cdb.h}.

The Class Data Base has a reference to all announced modules in the system. Only a module that is written in here can be instantiated, get into the SDB and be connected to other modules. These are the functions used to add a new module to the CDB. Every function has also a counterpart-macro that is defined in \dokuitalic{Include/spc.h}.


\dokutitleleveltree{swr{\textunderscore}spc{\textunderscore}get{\textunderscore}new{\textunderscore}desc}
\label{dd25439e1b1fdb200ced79a6cbf3a21a}%% swr_spc_get_new_desc
\index{swr_spc_get_new_desc} \index{CDB!Reference!swr_spc_get_new_desc}

 First, it has to ask for a new descriptor, using the following function:


\lstset{language=c}
\begin{lstlisting}
swr_spc_desc_t *swr_spc_get_new_desc(
int nbr_inputs,        // The maximum number of inputs
int nbr_outputs,       // The maximum number of outputs
int nbr_config_params, // How many configuration parameters
int nbr_stats_params); // How many statistic parameters

\end{lstlisting}
 This function allocates the necessary memory to store the required parameters and makes sure there is a place in the internal database. All required in- and outputs need to be defined, as well as all config- and stats-parameters. This can be done using the functions that are described hereafter. Each of this function is also used in a macro defined in \dokuitalic{Include/spc.h} for easier reference.


\dokutitleleveltree{swr{\textunderscore}spc{\textunderscore}define{\textunderscore}config{\textunderscore}parameter}
\label{ede8da0604c40260485d04f357e9b997}%% swr_spc_define_config_parameter
\index{swr_spc_define_config_parameter} \index{CDB!Reference!swr_spc_define_config_parameter} \index{UM_CONFIG_*}

Every configuration-parameter has to be defined in the order of appearance in the \dokuitalic{config{\textunderscore}t}-structure. The types have to be the same. Instead of using the following function, you can resort to the \dokuitalic{UM{\textunderscore}CONFIG{\textunderscore}*}-functions. So, to define an INTeger, you can use \dokuitalic{UM{\textunderscore}CONFIG{\textunderscore}INT("Name");}.


\lstset{language=c}
\begin{lstlisting}
int swr_spc_define_config_parameter(
  swr_spc_desc_t *cdb_desc,  // The description received
  parameter_type_t type,     // The type of the variable
  unsigned long flags,       // Eventual flags
  const char *name);         // The name to use in the software-radio

\end{lstlisting}
If you have the following configuration-structure:


\lstset{language=c}
\begin{lstlisting}
typedef struct{
  int slots;
  double amplitude;
} config_t;

\end{lstlisting}
then you need to define the two configuration-parameters with the following macros:


\lstset{language=c}
\begin{lstlisting}
UM_CONFIG_INT( "slots" );
UM_CONFIG_DOUBLE( "amp" );

\end{lstlisting}
Note that the order and the type need to correspond, but not the name!


\dokutitleleveltree{swr{\textunderscore}spc{\textunderscore}define{\textunderscore}stats{\textunderscore}parameter}
\label{cfc9b8d8c7f8203788eb51a86accfe12}%% swr_spc_define_stats_parameter
\index{swr_spc_define_stats_parameter} \index{CDB!Reference!swr_spc_define_stats_parameter} \index{UM_STATS_*}

Correspondingly to defining the config-parameters, all stats-parameters need to be defined, too. The same restrictions with regard to order and type apply. There are also macros that call this function. They are called \dokuitalic{UM{\textunderscore}STATS{\textunderscore}*}, where the types are the same as for the config-parameters.


\lstset{language=c}
\begin{lstlisting}
int swr_spc_define_stats_parameter(
  swr_spc_desc_t *desc,  // The description-handler
  parameter_type_t type, // The type of the stats
  unsigned long flags,   // Eventual flags
  const char *name);     // Name visible in the software-radio

\end{lstlisting}
If you have the following stats-structure:


\lstset{language=c}
\begin{lstlisting}
typedef {
  complex double channel;
  double SNR;
} stats_t;

\end{lstlisting}
Then you have to define them with the following macros:


\lstset{language=c}
\begin{lstlisting}
UM_STATS_DOUBLE_COMPLEX( "H" );
UM_STATS_DOUBLE( "SNR" );

\end{lstlisting}
Note again how the order and the types need to correspond, but not the names!


\dokutitleleveltree{Flags for define{\textunderscore}*{\textunderscore}parameter}
\label{1ccba499e446c87d88f652b4b910cca1}%% flags_for_define_parameter
There are two flags for the config- and stats-parameters that can be defined when defining these parameters: \index{PARAMETER_DEBUG} \index{PARAMETER_HIDE}


\begin{itemize}
\dokuitem  PARAMETER{\textunderscore}DEBUG shows a parameter only when debug-mode is active in visualize
\dokuitem  PARAMETER{\textunderscore}HIDE never shows a parameter in the visualize-tool
\end{itemize}

\dokutitleleveltree{Types for define{\textunderscore}*{\textunderscore}parameter}
\label{9b87825ee874490b20930cda0ab7c3ba}%% types_for_define_parameter
These are the valid types for the stats- and the config-parameters:\\ 

%% Table analyse:
%%    Numrows: 9
%%    Most Long row size: 42
%%    Choose table mode: tabular
\begin{figure}[h]
\begin{tabular}{lll}
\hline
\multicolumn{1}{|l|}{ }&\multicolumn{1}{l|}{UM{\textunderscore}CONFIG{\textunderscore}}&\multicolumn{1}{l|}{UM{\textunderscore}STATS{\textunderscore}}\\ 
\hline
\multicolumn{1}{|l|}{int}&\multicolumn{1}{l|}{INT}&\multicolumn{1}{l|}{INT}\\ 
\hline
\multicolumn{1}{|l|}{double}&\multicolumn{1}{l|}{DOUBLE}&\multicolumn{1}{l|}{DOUBLE}\\ 
\hline
\multicolumn{1}{|l|}{complex double}&\multicolumn{1}{l|}{DOUBLE{\textunderscore}COMPLEX}&\multicolumn{1}{l|}{DOUBLE{\textunderscore}COMPLEX}\\ 
\hline
\multicolumn{1}{|l|}{char[128]}&\multicolumn{1}{l|}{STRING128}&\multicolumn{1}{l|}{STRING128}\\ 
\hline
\multicolumn{1}{|l|}{block{\textunderscore}t}&\multicolumn{1}{l|}{-}&\multicolumn{1}{l|}{BLOCK}\\ 
\hline
\multicolumn{1}{|l|}{image{\textunderscore}t}&\multicolumn{1}{l|}{-}&\multicolumn{1}{l|}{IMAGE}\\ 
\hline
\multicolumn{1}{|l|}{void *}&\multicolumn{1}{l|}{POINTER}&\multicolumn{1}{l|}{POINTER}\\ 
\hline
\multicolumn{1}{|l|}{SYMBOL{\textunderscore}COMPLEX}&\multicolumn{1}{l|}{COMPLEX}&\multicolumn{1}{l|}{COMPLEX}\\ 
\hline
\end{tabular}
\end{figure}


\dokutitleleveltree{swr{\textunderscore}spc{\textunderscore}define{\textunderscore}input}
\label{e20aa3f255cef6b69bb3b89f69aa7ceb}%% swr_spc_define_input
\index{swr_spc_define_input} \index{CDB!Reference!swr_spc_define_input} \index{UM_INPUT}

All inputs to the module need to be defined using this function. Again, a macro exists that englobes this function. Contrary to the config- and stats- definitions, there is only one macro, and you have to give it a paramater for the type. Even if you intend to use only a subset of the inputs at any given time, you have to define all of them.


\lstset{language=c}
\begin{lstlisting}
int swr_spc_define_input(
  swr_spc_desc_t *desc,          // A pointer to the description
  swr_signal_type_t signal_type, // The signal type
  unsigned long flags);          // Eventual flags

\end{lstlisting}
 \index{swr_spc_define_output} \index{CDB!Reference!swr_spc_define_output} \index{UM_OUTPUT}

All outputs to the module need to be defined using this function. Again, a macro exists that englobes this function. Contrary to the config- and stats- definitions, there is only one macro, and you have to give it a paramater for the type. Even if you intend to use only a subset of the outputs at any given time, you have to define all of them.


\lstset{language=c}
\begin{lstlisting}
int swr_spc_define_output(
  swr_spc_desc_t *desc,
  swr_signal_type_t signal_type,
  unsigned long flags);

\end{lstlisting}
 \index{swr cdb register spc} \index{CDB!Reference!swr cdb register spc}


\lstset{language=c}
\begin{lstlisting}
swr_spc_id_t swr_cdb_register_spc(
  swr_spc_desc_t **desc,
  const char *name);

\end{lstlisting}

\dokutitleleveltree{Port Types}
\label{7c0c3665fb791b706aa0801314fc2340}%% port_types
\index{signal-types}

These are the valid signal-types for the in- and output and their respective type-name: 

%% Table analyse:
%%    Numrows: 10
%%    Most Long row size: 36
%%    Choose table mode: tabular
\begin{figure}[h]
\begin{tabular}{ll}
\hline
\multicolumn{1}{|l|}{ }&\multicolumn{1}{l|}{UM{\textunderscore}(IN/OUT)PUT(SIG{\textunderscore}}\\ 
\hline
\multicolumn{1}{|l|}{U8}&\multicolumn{1}{l|}{U8}\\ 
\hline
\multicolumn{1}{|l|}{SYMBOL{\textunderscore}S16}&\multicolumn{1}{l|}{SYMBOL{\textunderscore}S16}\\ 
\hline
\multicolumn{1}{|l|}{int}&\multicolumn{1}{l|}{S32}\\ 
\hline
\multicolumn{1}{|l|}{double}&\multicolumn{1}{l|}{DOUBLE}\\ 
\hline
\multicolumn{1}{|l|}{complex double}&\multicolumn{1}{l|}{DOUBLE{\textunderscore}COMPLEX}\\ 
\hline
\multicolumn{1}{|l|}{SYMBOL{\textunderscore}COMPLEX}&\multicolumn{1}{l|}{SYMBOL{\textunderscore}COMPLEX}\\ 
\hline
\multicolumn{1}{|l|}{SYMBOL{\textunderscore}COMPLEX{\textunderscore}S32}&\multicolumn{1}{l|}{SYMBOL{\textunderscore}COMPLEX{\textunderscore}S32}\\ 
\hline
\multicolumn{1}{|l|}{SYMBOL{\textunderscore}MMX}&\multicolumn{1}{l|}{SYMBOL{\textunderscore}MMX}\\ 
\hline
\multicolumn{1}{|l|}{SAMPLE{\textunderscore}S12}&\multicolumn{1}{l|}{SAMPLE{\textunderscore}S12}\\ 
\hline
\end{tabular}
\end{figure}

\index{CDB!Reference|)}


\dokutitleleveltree{Port Flags}
\label{027056120444d10a021546d28ae829a6}%% port_flags
The port-flags are described in \ref{subsub:port-flags-block-related} and can either be directly added when creating the ports, or in the {\textunderscore}init-block of the module by a line like


\lstset{language=c}
\begin{lstlisting}
  port_in(0).flags = SWR_PORT_OWN_MALLOC;

\end{lstlisting}

\dokutitleleveltwo{SDB}
\label{9c51816c474bb23a990ab22eddcd57a1}%% sdb
\label{sec:sdb} \index{SDB!Reference|(} Once a module is defined in the CDB, it can be \dokuitalic{instantiated}. When this is done, the SDB allocates private space for each instantiation and makes sure that each time an instance is called, it has the reference to its own private space.

Furthermore the SDB offers functions to have access to the config- and stats-structures from both the inside and the outside of a module. The difference is, that inside of the module you have an exact knowledge of the structure to change, while outside of the module you don't know anything else than the type and the name of the parameter to change or read.

Then the SDB offers some more special functions to access internal structures like the port in- and outputs and the profiling.


\dokutitleleveltree{Instantiation}
\label{7d387e631b9553c7d097159b52129bb3}%% instantiation
\index{SDB!Instantiation} \index{Instantiation}


\dokutitlelevelfour{swr{\textunderscore}chain{\textunderscore}create}
\label{subsub:swr_chain_create} \index{swr_chain_create}

Usually you will instantiate a \dokuitalic{chain} of modules, using the function \dokuitalic{swr{\textunderscore}chain{\textunderscore}create}. It takes a number of arguments to modules that should form a chain. The following arguments are valid: \index{NEW_SPC*} \index{OLD_SPC*} 


\begin{itemize}
\dokuitem  NEW{\textunderscore}SPC( "name" ) Instantiates the module "name" and connects its input 0 to the previous output (if any) and its output 0 to the next input (if any)
\dokuitem  NEW{\textunderscore}SPC{\textunderscore}IN( "name", in ) as NEW{\textunderscore}SPC, but the input port 'in' is connected to the output-port of the previous module
\dokuitem  NEW{\textunderscore}SPC{\textunderscore}OUT( "name", out ) as NEW{\textunderscore}SPC, but the output port 'out' is connected to the input-port of the next module
\dokuitem  NEW{\textunderscore}SPC{\textunderscore}IN{\textunderscore}OUT( "name", in, out ) as NEW{\textunderscore}SPC, but the input-port 'in' is connected to the previous module, and the output-port 'out' is connected to the next module
\dokuitem  NEW{\textunderscore}SPC{\textunderscore}VAR( "name", var ) same as NEW{\textunderscore}SPC, but the id of the instantiated module is stored in 'var'
\dokuitem  NEW{\textunderscore}SPC{\textunderscore}VAR{\textunderscore}IN( "name", var, in ) same as NEW{\textunderscore}SPC{\textunderscore}IN, but the id of the instantiated module is stored in 'var'
\dokuitem  NEW{\textunderscore}SPC{\textunderscore}VAR{\textunderscore}OUT( "name", var, out ) same as NEW{\textunderscore}SPC{\textunderscore}OUT, but the id of the instantiated module is stored in 'var'
\dokuitem  NEW{\textunderscore}SPC{\textunderscore}VAR{\textunderscore}IN{\textunderscore}OUT( "name", var, in, out ) same as NEW{\textunderscore}SPC{\textunderscore}IN{\textunderscore}OUT, but the id of the instantiated module is stored in 'var'
\dokuitem  OLD{\textunderscore}SPC( var ) same as NEW{\textunderscore}SPC, but instead of instantiating a new module, takes an alread instantiated module 'var'
\dokuitem  OLD{\textunderscore}SPC{\textunderscore}IN( var ) same as NEW{\textunderscore}SPC{\textunderscore}IN, but instead of instantiating a new module, takes an alread instantiated module 'var'
\dokuitem  OLD{\textunderscore}SPC{\textunderscore}OUT( var ) same as NEW{\textunderscore}SPC{\textunderscore}OUT, but instead of instantiating a new module, takes an alread instantiated module 'var'
\dokuitem  OLD{\textunderscore}SPC{\textunderscore}IN{\textunderscore}OUT( var ) same as NEW{\textunderscore}SPC{\textunderscore}IN{\textunderscore}OUT, but instead of instantiating a new module, takes an already instantiated module 'var'
\dokuitem  CHAIN{\textunderscore}END indicates that the chain is finished.
\end{itemize}
 The function returns an identifier to the created chain, so that the whole chain can be deleted when not in use anymore. In order to function correctly, at least two modules must be given as arguments.


\dokutitlelevelfour{swr{\textunderscore}sdb{\textunderscore}instantiate{\textunderscore}name}
\index{swr_sdb_instantiate_name} If you only want to create one instance, for example for a module that will be connected to multiple other modules, or for a module that doesn't have any in- or ouputs, you can use \dokuitalic{swr{\textunderscore}sdb{\textunderscore}instantiate{\textunderscore}name}. It takes as argument the name of the module and returns a sdb-id or -1 if an error occurs.


\dokutitlelevelfour{swr{\textunderscore}connection{\textunderscore}add}
\index{swr_connection_add}

Once you created a chain or some single modules, you might want to create connections 'by hand'. Then you need the following function:


\lstset{language=c}
\begin{lstlisting}
swr_conn swr_conn_add(
  swr_sdb_id sender,   // The id of the sending module
  int output,          // The output-port of the sending module
  swr_sdb_id receiver, // The id of the receiving module
  int input );         // The input-port of the receiving module

\end{lstlisting}

\dokutitleleveltree{Manipulating stats- and config-structures}
\label{61d830d677ef93c492cb2a68d203d475}%% manipulating_stats-_and_config-structures
\index{SDB!stats-structure} \index{SDB!config-structure}

There are two possibilities: either a module wants to change its own structures, or a part of the software-radio outside of the module wants to read or write one of the structures. This can be another module, or the visualize-tool. Due to the different sources that may be using the config- and stats-structures, they have to be mutex'ed, so that the information read is always up-to-date and doesn't change in a critical way.


\dokutitlelevelfour{Accessing own Structures}
For the modules own structures, a pair of functions exist to request the mutex to either the config- or the stats-structure. Once the mutex is aquired, the module can access it as it likes, before giving back the mutex. In order to force the user not to access the structures outside of a mutexed environment, a pointer to the structures is passed and is initialised with the address of the structure, or with NULL when the mutex is released. In this way the software-radio will immediatly show a bug when the structures are accessed outside of a mutexed environment. \index{swr_sdb_get_config_struct} \index{swr_sdb_get_stats_struct}

In order to aquire the mutex, one of the two functions has to be called:


\lstset{language=c}
\begin{lstlisting}
int swr_sdb_get_config_struct( swr_sdb_id id, void **str );
int swr_sdb_get_stats_struct( swr_sdb_id id, void **str );

\end{lstlisting}
As this is usually done in the module, the \dokuitalic{context}-variable is available, so it is used like this:


\lstset{language=c}
\begin{lstlisting}
config_t *config;
swr_sdb_get_config_struct( context->id, &config );

\end{lstlisting}
Now the module can read and write to the configuration-structure. The stats-structure is used in the same way. \index{swr_sdb_free_config_struct} \index{swr_sdb_free_stats_struct}

To release the mutex, also two functions exist:


\lstset{language=c}
\begin{lstlisting}
int swr_sdb_free_config_struct( swr_sdb_id id, void **str );
int swr_sdb_free_stats_struct( swr_sdb_id id, void **str );

\end{lstlisting}
As described above, they take a pointer to a pointer of the struct. In this way, using the pointer incorrectly causes a segmentation-fault (or a kernel-Oops in real-time).


\dokutitlelevelfour{Accessing other Structures}
When accessing structures from other modules, one not only has to take care about mutual exclusion, but also one has to notify the module that something changed, at least in the case of a configuration-change.

To change the configuration of another module, one has to know the id of that module, the name of the configuration-variable and the type. Then one can set the value using one of the \dokuitalic{swr{\textunderscore}sdb{\textunderscore}set{\textunderscore}config{\textunderscore}*}-functions: \index{swr_sdb_set_config_pointer} \index{swr_sdb_set_config_int} \index{swr_sdb_set_config_complex} \index{swr_sdb_set_config_double} \index{swr_sdb_set_config_symbol}


\lstset{language=c}
\begin{lstlisting}
int swr_sdb_set_config_pointer(  swr_sdb_id id, char *name, void *value );
int swr_sdb_set_config_int(  swr_sdb_id id, char *name, int value );
int swr_sdb_set_config_complex(  swr_sdb_id id, char *name, complex double value );
int swr_sdb_set_config_double(  swr_sdb_id id, char *name, double value );
int swr_sdb_set_config_symbol(  swr_sdb_id id, char *name, SYMBOL_COMPLEX value );

\end{lstlisting}
There is a special case where one wants to wait for the reconfiguration of the module, for example when changing a range of configurations from the same module. For this reason, the 'id'-parameter of the above functions can be chosen to be negative. Internally, all sdb-ids are positive, so a negative id always points to a unique module and stands for: "don't reconfigure right now". The other case is when reading stats-structures of other modules. The function-names are:


\lstset{language=c}
\begin{lstlisting}
void* swr_sdb_get_stats_pointer( ... );
int swr_sdb_get_stats_int( ... );
complex double swr_sdb_get_stats_complex( ... );
double swr_sdb_get_stats_double( ... );
SYMBOL_COMPLEX swr_sdb_get_stats_symbol( ... );
block_t swr_sdb_get_stats_block( ... );
image_t swr_sdb_get_stats_image( ... );

\end{lstlisting}
All functions have {\textbackslash}texttt{swr{\textunderscore}sdb{\textunderscore}id id, char *name} as parameter. Here a negative sdb-id as 'id'-parameter is invalid.


\dokutitleleveltree{Other Functions}
\label{212f94d16c6635fcfb8c18866fe99ffd}%% other_functions
Most other functions from the SDB are only used internally and are documented in \dokuitalic{Include/sdb.h}. The only exception is the function to read and display the profile of a module: \index{swr_sdb_show_profile}


\lstset{language=c}
\begin{lstlisting}
int swr_sdb_show_profile( swr_sdb_id id );

\end{lstlisting}
which displays all available profiles of the given module complete with number of calls, total time and average time. \index{SDB!Reference|)}


\dokutitleleveltwo{Subsystem}
\label{71f7b1ba9fdbe73d19d4343685d7acad}%% 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}
\dokuitem  Messages which are passed between subsystems\dokufootnote{Subsystem and Module are interchangeable in this context}
\dokuitem  Subsystem-flags reflecting the state of the subsystem
\dokuitem  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.


\dokutitleleveltree{Messages}
\label{de70938849b75d3db63bba421c93e018}%% 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}
\dokuitem  Basic handling involves everything to set-up the module and is rarely or never called during life-time
\dokuitem  Reconfiguration of the module is also pretty rare for most of the modules
\dokuitem  Data Propagation is the workhorse of the subsystem and modules
\end{itemize}
 Each group is described in more detail in the following sections.


\dokutitlelevelfour{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 \dokuitalic{SUBS{\textunderscore}MSG{\textunderscore}CONNECT} to both subsystems that are to be connected together. As payload for the message one should give a structure of type swr{\textunderscore}propagation{\textunderscore}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 \dokuitalic{SUBS{\textunderscore}MSG{\textunderscore}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 \dokuitalic{SUBS{\textunderscore}MSG{\textunderscore}NEW{\textunderscore}TRACK} message, after which the subsystem will check the tracking-list on each data-processing to update the corresponding tracks. Similarly, \dokuitalic{SUBS{\textunderscore}MSG{\textunderscore}NO{\textunderscore}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{\textunderscore}MSG{\textunderscore}NEW{\textunderscore}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 \dokuitalic{SUBS{\textunderscore}MSG{\textunderscore}THREAD}\dokufootnote{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{\textunderscore}MSG{\textunderscore}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 \dokuitalic{SUBS{\textunderscore}MSG{\textunderscore}EXIT}-message. All input- and output-ports have to be cleaned up before sending this messasge, otherwise undefined behaviour might occur.


\dokutitlelevelfour{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 \dokuitalic{SUBS{\textunderscore}MSG{\textunderscore}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{\textunderscore}STATUS{\textunderscore}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 \dokuitalic{SUBS{\textunderscore}MSG{\textunderscore}DATA}-message to the top module. This message will test for SUBS{\textunderscore}STATUS{\textunderscore}MULTI{\textunderscore}IN and SUBS{\textunderscore}STATUS{\textunderscore}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{\textunderscore}MSG{\textunderscore}DATA-message.

\index{Subsystem!Messages!SUBS_MSG_PING} A small test-message that survived from the depths of the development is the \dokuitalic{SUBS{\textunderscore}MSG{\textunderscore}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 \dokuitalic{SUBS{\textunderscore}MSG{\textunderscore}USER}-message exists. The payload of the message can contain whatever is accurate. Upon reception of this message, the user{\textunderscore}msg-function of the module is called, with the payload as argument.


\dokutitlelevelfour{Reconfiguration}
\index{Subsystem!Messages!SUBS_MSG_RECONFIG}

Whenever a part of the software-radio thinks that the configuration might have changed, it sends a \dokuitalic{SUBS{\textunderscore}MSG{\textunderscore}RECONFIG}-message to the corresponding module. If the receiving module has the flag SUBS{\textunderscore}STATUS{\textunderscore}RECONFIG set, it will call the reconfig-function of the module. Furthermore the configure{\textunderscore}inputs or configure{\textunderscore}outputs-function is called, depending on whether the SUBS{\textunderscore}STATUS{\textunderscore}RESIZE{\textunderscore}UP or -DOWN flag is set.

\index{Subsystem!Messages!SUBS_MSG_RESIZE} Upon arrival of a message, the subsystem stores all input- and output-port addresses, as well as the sizes. If something changes during the execution of the message, a \dokuitalic{SUBS{\textunderscore}MSG{\textunderscore}RESIZE}-message is sent to all ports that changed size or the data-pointer.


\dokutitleleveltree{Subsytem-Flags}
\label{0aed7102ffd961ed60f857de16117ff3}%% subsytem-flags
\index{Subsystem!Flags} These flags reflect the internal state of the susbsystem and are split in these groups:


\begin{itemize}
\dokuitem  Propriety reflect a general state of this subsystem which is more or less static
\dokuitem  User-defined, that is, set in the {\textunderscore}init-part of the module
\dokuitem  State for transient information about the module
\end{itemize}

\dokutitlelevelfour{Propriety}
\index{Subsystem!Flags!SUBS_STATUS_THREAD} \index{Subsystem!Flags!SUBS_STATUS_TRACKED} \index{Subsystem!Flags!SUBS_STATUS_RESIZE_DOWN} \index{Subsystem!Flags!SUBS_STATUS_RESIZE_UP}

All these flags are set internally by the software-radio and change very rarely.


\begin{itemize}
\dokuitem  SUBS{\textunderscore}STATUS{\textunderscore}THREAD module has been threaded
\dokuitem  SUBS{\textunderscore}STATUS{\textunderscore}TRACKED there is a stats{\textunderscore}track list with this module
\dokuitem  SUBS{\textunderscore}STATUS{\textunderscore}RESIZE{\textunderscore}DOWN resize-messages go down
\dokuitem  SUBS{\textunderscore}STATUS{\textunderscore}RESIZE{\textunderscore}UP resize-messages go up
\end{itemize}
 The RESIZE-flags are set the first time a module receives a resize-message. This is done to know in the future which port-sizes have precedence, because in some situations it's not straightforward to decide what to do if there is not a clear preference for a certain resize-direction.


\dokutitlelevelfour{User-defined}
\index{Subsystem!Flags!SET_STATUS} \index{SET_STATUS}

All these flags can be set in the {\textunderscore}init-part of the module by inserting a line


\small
\begin{verbatimtab}

SET_STATUS( RESIZE_NONE );

\end{verbatimtab}
\normalsize
One has to note that with the SET{\textunderscore}STATUS-command the SUBS{\textunderscore}STATUS{\textunderscore}-part of the flag has to be omitted.

\index{SUBS_STATUS_*|see{Subsystem/Flags}} \index{Subsystem!Flags!SUBS_STATUS_RESIZE_NONE} A module like the STFA only generates resize-requests, and will never receive one. The usual logic of the subsystem forbids this, but if you set the \dokuitalic{SUBS{\textunderscore}STATUS{\textunderscore}RESIZE{\textunderscore}NONE}-flag the subsystem will honor this behaviour.

\index{Subsystem!Flags!SUBS_STATUS_RESIZE_BOTH} While some modules don't want to receive resize-requests, other modules like the test{\textunderscore}data{\textunderscore}rcv need to be informed by changes on both the input and the output. If this is the case, you have to set the \dokuitalic{SUBS{\textunderscore}STATUS{\textunderscore}RESIZE{\textunderscore}BOTH}-flag. Afterwards the module will be alerted by any size-change on its input- and output-ports, and the subsystem won't complain about this strange behaviour.

\index{Subsystem!Flags!SUBS_STATUS_PREPARE_SWALLOW} The SUBS{\textunderscore}MSG{\textunderscore}PREPARE-message traverses all attached modules. Of course it has to stop at the STFA, else every module will be in \dokuitalic{prepare}-status. If a module has the \dokuitalic{SUBS{\textunderscore}STATUS{\textunderscore}PREPARE{\textunderscore}SWALLOW}-flag set, then it will silently drop all requests to prepare and it will not inform other modules attached to itself.

\index{Subsystem!Flags!SUBS_STATUS_MULTI_IN} If you have a module with multiple intputs, and you want to make sure that all connected inputs contain up-to-date data, you can set the \dokuitalic{SUBS{\textunderscore}STATUS{\textunderscore}MULTI{\textunderscore}IN}-flag. This will tell the subsystem to make sure that all inputs contain data before calling the pdata-method of the module.

An important issue when using the MULTI{\textunderscore}IN-flag is the fact that the subsystem will try to make sure that all inputs are from the same time-instant. For this reason, the inputs of the module that has the MULTI{\textunderscore}IN-flag set need to arrive in chronological order. Taking the example of a MIMO{\textunderscore}LDPC-decoder, the first input has to come from the first STFA, the second input from the second STFA and so on. This is the only way that the subsytem can make sure that all inputs come from the same frame.


\dokutitlelevelfour{State}
The states described here are very short-lived. They usually indicate a work in progress or a needed action.

\index{Subsystem!Flags!SUBS_STATUS_RECONF} \index{Subsystem!Flags!SUBS_STATUS_WORKING} \index{Subsystem!Flags!SUBS_STATUS_PREPARE} \index{Subsystem!Flags!SUBS_STATUS_LISTED}


\begin{itemize}
\dokuitem  SUBS{\textunderscore}STATUS{\textunderscore}RECONF is set when the configuration-parameters have been changed, but before the module's reconfig-method has been called.
\dokuitem  SUBS{\textunderscore}STATUS{\textunderscore}WORKING indicates a module that is in it's pdata-method
\dokuitem  SUBS{\textunderscore}STATUS{\textunderscore}PREPARE is a module that is 'locked' and ready to process data.
\dokuitem  SUBS{\textunderscore}STATUS{\textunderscore}LISTED in conjunction with the debug-interface, indicates a module that is known to the visualize-tool
\end{itemize}

\dokutitleleveltree{Port-Flags}
\label{4cf61144d7c1f8c1d3fda51dac58a6f7}%% port-flags
These flags are individual for each input- and output-port. They can be combined together, although not all combinations make sense. There are mainly two groups of port-flags:


\begin{itemize}
\dokuitem  Block-related which define how the block is allocated and who takes care about malloc/free
\dokuitem  Data-passing which describe when a block of data is ready or when it needs to change
\end{itemize}

\dokutitlelevelfour{Block-related}
\label{subsub:port-flags-block-related} Besides the usual block- (port-)handling, some modules need a more special handling. These flags help define such special ports. \index{Subsystem!Ports!SUBS_PORT_OWN_MALLOC} \index{Subsystem!Ports!SUBS_PORT_OTHER_FREE} \index{Subsystem!Ports!SUBS_PORT_OTHER_MALLOC} \index{Subsystem!Ports!SUBS_PORT_THIS_FREE} \index{Subsystem!Ports!SUBS_PORT_PASSED_THROUGH}


\begin{itemize}
\dokuitem  SWR{\textunderscore}PORT{\textunderscore}OWN{\textunderscore}MALLOC this means that the module wants to keep track on it's own about the different malloc/free
\dokuitem  SWR{\textunderscore}PORT{\textunderscore}OTHER{\textunderscore}FREE another port is responsible for freeing this data
\dokuitem  SWR{\textunderscore}PORT{\textunderscore}OTHER{\textunderscore}MALLOC another port is allocating the memory
\dokuitem  SWR{\textunderscore}PORT{\textunderscore}THIS{\textunderscore}FREE this port is responsible for freeing the data
\dokuitem  SWR{\textunderscore}PORT{\textunderscore}PASSED{\textunderscore}THROUGH this port passes the data through
\end{itemize}

\dokutitlelevelfour{Signal-passing}
\index{Subsystem!Ports!SUBS_PORT_DATA} The flag \dokuitalic{SUBS{\textunderscore}PORT{\textunderscore}DATA} is set whenever a module requests a buffer by using \dokuitalic{buffer{\textunderscore}out(port)}. When terminating the subsystem-call, it checks for this flag on all output-ports and makes sure that the appropriate attached modules are called.

\index{Subsystem!Ports!SUBS_PORT_GOT_RESIZE} The \dokuitalic{SUBS{\textunderscore}PORT{\textunderscore}GOT{\textunderscore}RESIZE}-flag is only used internally to mark a port that already has been resized. Without it, one could have a ping-pong of two ports that try to resize each other mutually. \index{Subsystem!Reference|)}


\dokutitleleveltwo{Module}
\label{22884db148f0ffb0d830ba431102b0b5}%% module
\index{Module|(}

This section gives an overview of the module-creation and the use of it. Even though \ref{cha:conception_to_measurement} gives an example of how to create a new module, it is a good idea to read at least this introduction, so that you know what it is about.


\dokutitleleveltree{General introduction}
\label{7b3705c2ea8f8a39e0a9f9a2148ca9b4}%% general_introduction
Before a module can be used, it usually has to go through the following steps:


\begin{enumerate}\dokuitem  Registration with the CDB, usually in \dokuitalic{module{\textunderscore}init}, this happens when loading the module into memory
\dokuitem  Instantiation, which means setting up the needed memory and calling \dokuitalic{init}
\dokuitem  A call to \dokuitalic{reconfig} to assure that everything is OK
\end{enumerate}
 \index{swr_sdb_instantiate_name} \index{swr_sdb_instantiate_id} The points 2 and 3 are done automatically when calling \dokuitalic{swr{\textunderscore}sdb{\textunderscore}instantiate{\textunderscore}*} and may happen more than once, where a new memory-block is allocated for each instantiation, in order to make sure that all copies of the module work in an independent way.

Once this has been done, a module can be asked to do one of the following tasks: 
\begin{lyxlist}{00.00.0000}
\index{Module!pdata}
\item [pdata]Process an incoming data-block and eventually produce some output-data \index{Module!reconfig}


\item [reconfig]Reconfigure itself because one of the configuration variables have been changed \index{Module!resize}


\item [resize]Re-calculate its input- and output-sizes \index{Module!msg}


\item [custom-msg]React to a user-message \index{Module!finalize}


\item [finalize]Clean up allocated values

\end{lyxlist}

\index{swr_sdb_set_configure} The names to the left are the internal names used in the module-definition. You will never call these functions directly, but rather ask the MSR to do something that will then call one of these functions. So if you reconfigure one module using \dokuitalic{swr{\textunderscore}sdb{\textunderscore}set{\textunderscore}configure{\textunderscore}int} you ask the MSR to set the configuration of this module-instance to a certain value and to call the appropriate \dokuitalic{reconfig} function.


\dokutitleleveltree{Data Structures}
\label{9466edd02bad586f9ccf200a84a4dafd}%% data_structures
\label{sub:Data-structures}

A module has three different data-structures: 
\begin{lyxlist}{00.00.0000}

\item [config]Where other modules may ask for a change in the behaviour


\item [stats]Results from the signal-processing


\item [private]Internal structure that is not available to the outside

\end{lyxlist}

While the first two have already been discussed a bit, the third is new. It may be used for internal tables built depending on the configuration, it may contain a copy of important config-parameters or anything else needed for a module to function correctly. An important point: the private-structure is personal to each copy of the module, so it is not suited to keep 'global' options.

The config and stats structures are protected by mutexes, as they are open to all other modules to use. So in order to use a config-structure, one has first to call

\index{swr_sdb_get_config_struct} 


\lstset{language=c}
\begin{lstlisting}
swr_sdb_get_config_struct( context->id, (void**)&config );

\end{lstlisting}
before being able to use \dokuitalic{config-{\textbackslash}textgreater{}something}. To free the structure, use

\index{swr_sdb_free_config_struct} 


\lstset{language=c}
\begin{lstlisting}
swr_sdb_free_config_struct( context->id, (void**)&config );

\end{lstlisting}
after which other modules can alos access this structure. The same goes for the stats-structure. You don't have to make this extra effort with the private-structure, as they are local to each instance anyway.


\dokutitleleveltree{Data Types}
\label{276d269c22fa4df82a9c11c55c2ff5d0}%% data_types
\label{sub:Data-types}


\dokutitlelevelfour{For Config and Stats}
 \dokubold{Blocks} \label{par:Blocks}

\index{Data Types!Block} Blocks are a defined in the following way: 


\small
\begin{verbatimtab}

typedef struct {
  void *data;
  int size;
  swr_signal_type_t type;
} block_t;

\end{verbatimtab}
\normalsize
They can be used to give a window into an internal vector. The matched-filter module for example has a block that points to the matched-filter used, so the user can see the matched-filter in real-time, using the visualisation tool.

The \dokuitalic{data} pointer has to point to the vectory you want to display, \dokuitalic{size} is the size in units of \dokuitalic{type}, which is one of the Data-Types described in here (w/o \dokuitalic{Block}, of course).

\dokubold{SYMBOL{\textunderscore}COMPLEX} \index{Data Types!SYMBOL_COMPLEX}


\lstset{language=c}
\begin{lstlisting}
typedef struct {
  short int real;
  short int imag;
} SYMBOL_COMPLEX;

\end{lstlisting}
\dokubold{SYMBOL{\textunderscore}COMPLEX{\textunderscore}S32} \index{Data Types!SYMBOL_COMPLEX_S32}


\lstset{language=c}
\begin{lstlisting}
typedef struct {
  int real;
  int imag;
} SYMBOL_COMPLEX;

\end{lstlisting}
\dokubold{DOUBLE{\textunderscore}COMPLEX} \index{Data Types!DOUBLE_COMPLEX}


\lstset{language=c}
\begin{lstlisting}
typedef struct {
  double real;
  double imag;
} double_complex;

\end{lstlisting}
This structure is compatible with the \dokuitalic{complex double} declaration from C. So, if you include "complex.h", you can declare a \dokuitalic{complex double} and tell the subsystem to use it as such.

\dokubold{SYMBOL{\textunderscore}MMX} \index{Data Types!SYMBOL_MMX}

Describes one complex symbol in a special format. It is done like this:

$Re_{0} Im_{0} -Im_{0} Re_{0}$


The utility of this is that if we want to do a complex multiplication, we can arrange the second complex number in the following way:

$Re_{0} Im_{0} Re_{0} Im_{0}$


And then a special MMX-operation on these two complex numbers yields directly the result, separated into real and imaginary part. This is very useful for convolutions that need to be optimised.

\dokubold{Simple Data-types}


\begin{lyxlist}{00.00.0000}
\index{Data Types!U8}
\item [U8]Unsigned 8-bit \index{Data Types!S8}


\item [S8]Signed 8-bit \index{Data Types!U32}


\item [U32]Unsigned 32-bit \index{Data Types!S32}


\item [S32]Signed 32-bit \index{Data Types!SAMPLE_S12}


\item [SAMPLE{\textunderscore}S12]Signed 12-bit, where the 12 upper bits are used. For the available hardware, the lower 4 bits signal RX/TX \index{Data Types!SAMPLE_S16}


\item [SYMBOL{\textunderscore}S16]Signed 16-bit real symbol \index{Data Types!DOUBLE}


\item [DOUBLE] a double floating-point value

\end{lyxlist}


\dokutitleleveltree{Macros}
\label{264a818e305e0550c3ee63761dd3d911}%% macros
\label{sub:Macros-to-use}

Each function that is defined in a module takes at least one argument: \dokuitalic{swr{\textunderscore}sdb{\textunderscore}t *context} In there all necessary information to distinguish one instance of another is stored. As this information may be a bit difficult to access, a lot of macros allow easy access to this information. These macros are defined in \dokuitalic{spc.h} which is already included in the templates.


\dokutitlelevelfour{module{\textunderscore}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}
\index{Macros!UM_CONFIG_INT}
\item [UM{\textunderscore}CONFIG{\textunderscore}INT]adds an int-parameter to the configuration \index{Macros!UM_CONFIG_COMPLEX}


\item [UM{\textunderscore}CONFIG{\textunderscore}COMPLEX]adds a complex-parameter to the configuration \index{Macros!UM_CONFIG_DOUBLE}


\item [UM{\textunderscore}CONFIG{\textunderscore}DOUBLE]adds a double-parameter to the configuration \index{Macros!UM_CONFIG_DOUBLE_COMPLEX}


\item [UM{\textunderscore}CONFIG{\textunderscore}DOUBLE{\textunderscore}COMPLEX]adds a double{\textunderscore}complex-parameter to the configuration \index{Macros!UM_CONFIG_STR128}


\item [UM{\textunderscore}CONFIG{\textunderscore}STR128]adds a char[128] parameter to the configuration \index{Macros!UM_CONFIG_POINTER}


\item [UM{\textunderscore}CONFIG{\textunderscore}POINTER]adds a void* parameter to the configuration \index{Macros!UM_STATS_INT}


\item [UM{\textunderscore}STATS{\textunderscore}INT]adds an int-parameter to the statistics \index{Macros!UM_STATS_COMPLEX}


\item [UM{\textunderscore}STATS{\textunderscore}COMPLEX]adds a complex parameter to the stats \index{Macros!UM_STATS_DOUBLE}


\item [UM{\textunderscore}STATS{\textunderscore}DOUBLE]adds a double-parameter to the statistics \index{Macros!UM_STATS_DOUBLE_COMPLEX}


\item [UM{\textunderscore}STATS{\textunderscore}DOUBLE{\textunderscore}COMPLEX]adds a double{\textunderscore}complex-parameter to the statistics \index{Macros!UM_STATS_STR128}


\item [UM{\textunderscore}STATS{\textunderscore}STR128]adds a char[128] parameter to the statistics \index{Macros!UM_STATS_POINTER}


\item [UM{\textunderscore}STATS{\textunderscore}POINTER]adds a void* parameter to the statistics \index{Macros!UM_STATS_BLOCK}


\item [UM{\textunderscore}STATS{\textunderscore}BLOCK]adds a block{\textunderscore}t parameter to the statistics, see $<$ref$>$par:Blocks$<$/ref$>$ \index{Macros!UM_STATS_IMAGE}


\item [UM{\textunderscore}STATS{\textunderscore}IMAGE]adds an image to the stats \index{Macros!UM_INPUT}


\item [UM{\textunderscore}INPUT]adds an input-port, for the types see $<$ref$>$sub:Data-types$<$/ref$>$, and allows to define a flag \index{Macros!UM_OUTPUT}


\item [UM{\textunderscore}OUTPUT]adds an output-port, for the types see $<$ref$>$sub:Data-types$<$/ref$>$, and allows to define a flag

\end{lyxlist}


\dokutitlelevelfour{other functions}

\begin{lyxlist}{00.00.0000}
\index{Macros!private}
\item [private]allows access to this modules private-structure \index{Macros!size_in}


\item [size{\textunderscore}in(n)]returns the input-size of the port \dokuitalic{n}. This may also be used to assign a size to a port, so \dokuitalic{size{\textunderscore}in(0)=256;} is valid. \index{Macros!size_out}


\item [size{\textunderscore}out(n)]returns the output-size of the port \dokuitalic{n}. Allocating sizes is possible as with \dokuitalic{size{\textunderscore}in}. \index{Macros!data_available}


\item [data{\textunderscore}available(n)]returns true if the input-port \dokuitalic{n} has some new data \index{Macros!buffer_in}


\item [buffer{\textunderscore}in(n)]returns a pointer to the input-buffer \dokuitalic{n} and clears the data-flag on this input-port \index{Macros!buffer_out}


\item [buffer{\textunderscore}out(n)]returns a pointer to the output-buffer \dokuitalic{n} and sets the data-flag on this output-port \index{Macros!call_module}


\item [call{\textunderscore}module]sends a MSG{\textunderscore}DATA to the module \index{Macros!make_thread}


\item [make{\textunderscore}thread]puts a module in a thread

\end{lyxlist} \index{Module|)} 




\dokutitlelevelone{Makefile}
\label{cd5dbf3629c558b0104ba8f0937d6816}%% makefile
\label{cd5dbf3629c558b0104ba8f0937d6816}%%Start: makefile => /var/www/html/ipgwww/data/pages/makefile.txt

\dokutitleleveltwo{Make Arguments}
\label{368111a1698f3e080afe31495fa884ed}%% make_arguments
\label{sub:Make-Parameters} \index{Make} Whenever you are in a sub-directory of the software-radio, you can give some arguments to the \dokuitalic{make} command. There are arguments that may be used everywhere in the tree, some that are only valid in the \dokuitalic{Radios/*} subdirectories and some arguments that are only valid in the subdirectories that contain code.


\dokutitleleveltree{Common}
\label{9efab2399c7c560b34de477b9aa0a465}%% common
These arguments may be used anywhere in the tree (except the \dokuitalic{Tools}-directory): 
\begin{lyxlist}{00.00.0000}
\index{Make!clean}
\item [clean]Remove all object-files in all sub-trees \index{Make!whole}


\item [whole]Re-compile the whole tree \index{Make!base}


\item [base]Re-compile base only \index{Make!tools}


\item [tools]Re-compile tools only \index{Make!modules}


\item [modules]Re-compile modules only, additionally \dokuitalic{mod{\textunderscore}coding}, \dokuitalic{mod{\textunderscore}data}, \dokuitalic{mod{\textunderscore}general}, \dokuitalic{mod{\textunderscore}macro}, \dokuitalic{mod{\textunderscore}signal} re-compile only this special modules-directory \index{Make!show}


\item [show]Starts the visualisation-tool \index{Make!server}


\item [server]Start the channel-server \index{Make!kill}


\item [kill]End all simulations as well as the channel-server \index{Make!cleanproc}


\item [cleanproc]Remove all simulation-directories from \dokuitalic{/tmp} \index{Make!rmall}


\item [rmall]Unloads all real-time modules and stops RTLinux \index{Make!cvs_up}


\item [cvs{\textunderscore}up]Updates the \dokuitalic{whole} SRadio/*-tree using CVS\dokufootnote{Concurrent Versions System} \index{Make!cvs_commit}


\item [cvs{\textunderscore}commit]Commits \dokuitalic{all} changes to the SRadio/*-tree

\end{lyxlist}


\dokutitleleveltree{Radios}
\label{92beebeb47dc6b2d5d148ba922f1a91c}%% radios
Arguments that can be used in the subdirectories of \dokuitalic{Radios}/ 
\begin{lyxlist}{00.00.0000}
\index{Make!bsms}
\item [bsms]Starts channel-server and both BS and MS\dokufootnote{Microsoft} part. To stop, run \dokuitalic{make kill} \index{Make!show_bsms}


\item [show{\textunderscore}bsms]Like \dokuitalic{bsms}, but also runs the visualisation-tool \index{Make!wait_bsms}


\item [wait{\textunderscore}bsms]Like \dokuitalic{bsms}, but stops the MS\dokufootmark{2} after 20 seconds and the BS after 30 seconds. Most useful to check whether a radio exits nicely, before trying it in real-time \index{Make!short_wait_bsms}


\item [short{\textunderscore}wait{\textunderscore}bsms]Like \dokuitalic{wait{\textunderscore}bsms} but for the impatient: BS waits for 10 seconds, MS\dokufootmark{2} for 5 seconds. Attention: things might not be correctly initialised after 5 seconds! \index{Make!mc}


\item [mc]Starts channel-server and both Server and Client part. To stop, run \dokuitalic{make kill} \index{Make!show_mc}


\item [show{\textunderscore}mc]Like \dokuitalic{mc}, but also runs the visualisation-tool \index{Make!wait_mc}


\item [wait{\textunderscore}mc]Like \dokuitalic{mc}, but stops the Client after 20 seconds and the Server after 30 seconds. Most useful to check whether a radio exits nicely, before trying it in real-time \index{Make!short_wait_mc}


\item [short{\textunderscore}wait{\textunderscore}mc]Like \dokuitalic{wait{\textunderscore}mc} but for the impatient: Server waits for 10 seconds, Client for 5 seconds. Attention: things might not be correctly initialised after 5 seconds!

\end{lyxlist}


\dokutitleleveltree{Code}
\label{c13367945d5d4c91047b3b50234aa7ab}%% code
Useful arguments when you are developing code 
\begin{lyxlist}{00.00.0000}
\index{Make!user}
\item [user]Loads the modules defined in the Makefile for simulation and unloads them \index{Make!user_show}


\item [user{\textunderscore}show]Like \dokuitalic{user}, but also starts the visualisation-tool \index{Make!user_wait}


\item [user{\textunderscore}wait]Like \dokuitalic{user}, but doesn't unload the modules \index{Make!user_wait_5}


\item [user{\textunderscore}wait{\textunderscore}5]Like \dokuitalic{user}, but waits for 5 seconds before unloading \index{Make!user_wait_10}


\item [user{\textunderscore}wait{\textunderscore}10]waits for 10 seconds before unloading \index{Make!user_wait_20}


\item [user{\textunderscore}wait{\textunderscore}20]waits for 20 seconds before unloading \index{Make!user_wait_30}


\item [user{\textunderscore}wait{\textunderscore}30]waits for 30 seconds before unloading \index{Make!user_wait_60}


\item [user{\textunderscore}wait{\textunderscore}60]waits for 60 seconds before unloading \index{Make!ddd}


\item [ddd]Start the graphical debugger in simulation-mode \index{Make!debug}


\item [debug]Start gdb in simulation-mode \index{Make!rf}


\item [rf]Starts the radio in real-time mode \index{Make!rf_tail}


\item [rf{\textunderscore}tail]Like \dokuitalic{rf} but also tails \dokuitalic{/var/log/messages} where \dokuitalic{PR{\textunderscore}DBGs} will be written to \index{Make!rf_show}


\item [rf{\textunderscore}show]Like \dokuitalic{rf{\textunderscore}tail} but launches the visualisation-tool \index{Make!rmall}


\item [rmall]Unloads all modules from real-time mode

\end{lyxlist} 




\dokutitlelevelone{DBG-interface}
\label{158f48c00e990c1d217815f293627562}%% dbg-interface
\label{158f48c00e990c1d217815f293627562}%%Start: dbg-interface => /var/www/html/ipgwww/data/pages/dbg-interface.txt
\label{chap:dbg-interface}


\dokutitleleveltwo{Command-syntax}
\label{90f6b97528e8fb5efec0fa1d9efd974d}%% command-syntax

\dokutitleleveltree{list{\textunderscore}modules}
\label{2d93c415ad431de5ac2b2e3a65044cd1}%% list_modules
\index{DBG!list_modules} returns a list of all available modules

\dokubold{Arguments} none

\dokubold{Returns} a module{\textunderscore}id,name list of all modules available, where module{\textunderscore}id is to be used for reference, while name reflects the spc-name of the module. The returned list is sorted on module{\textunderscore}id. 


\dokutitleleveltree{list{\textunderscore}tag{\textunderscore}modules}
\label{def84dc388132283b45a1bb153aa0292}%% list_tag_modules
\index{DBG!list_tag_modules} returns a list of all available modules and tags all modules as 'seen'. See also \dokuitalic{list{\textunderscore}new{\textunderscore}modules}.

\dokubold{Arguments} none

\dokubold{Returns} a module{\textunderscore}id,name list of all modules available, where module{\textunderscore}id is to be used for reference, while name reflects the spc-name of the module. The returned list is sorted on module{\textunderscore}id. 


\dokutitleleveltree{list{\textunderscore}new{\textunderscore}modules}
\label{7b19bd485dc2fee69951450adc5d7066}%% list_new_modules
\index{DBG!list_new_modules} only returns modules that are not tagged as 'seen'. Useful only in conjunction with \dokuitalic{list{\textunderscore}tag{\textunderscore}modules}. All returned modules are tagged as 'seen', too.

\dokubold{Arguments} none

\dokubold{Returns} a module{\textunderscore}id,name list of all modules available, where module{\textunderscore}id is to be used for reference, while name reflects the spc-name of the module. The returned list is sorted on module{\textunderscore}id. 


\dokutitleleveltree{show{\textunderscore}all}
\label{1cbdb2953d92c3e10c8e2deeda188cee}%% show_all
\index{DBG!show_all} gives the whole description of a module

\dokubold{Arguments} the id of the module

\dokubold{Returns} 
\begin{lyxlist}{00.00.0000}

\item [input]number of inputs, followed by a type,len - list for every input


\item [output]number of outputs, followed by a conn{\textunderscore}id,conn{\textunderscore}index,type,len list for every output, where conn{\textunderscore}id and conn{\textunderscore}index point to the module and port connected. If this port is not connected, conn{\textunderscore}id and conn{\textunderscore}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{lyxlist}


\dokutitleleveltree{show{\textunderscore}*}
\label{a7dd12b1dab17d25467b0b0a4c8d4a92}%% show
\index{DBG!show_input} \index{DBG!show_output} \index{DBG!show_config} \index{DBG!show_stats} Returns only part of the description. "*" can be one of {input, output, config, stats} and will return the corresponding information.

\dokubold{Arguments} the id of the module

\dokubold{Returns} Like \dokuitalic{show{\textunderscore}all}, but only the asked argument 


\dokutitleleveltree{get{\textunderscore}output}
\label{36097eb140badf0eafacc943821ce2ad}%% get_output
\index{DBG!get_output} returns a given output of a given module

\dokubold{Arguments} module{\textunderscore}id,port{\textunderscore}nbr

\dokubold{Returns} size,type,values where values are decimal, comma-seperated values. For complex numbers, each value is a (real,imag)-pair. 


\dokutitleleveltree{get{\textunderscore}block}
\label{75140f7c55e707d40a62452bd13f1c77}%% get_block
\index{DBG!get_block} Returns the values of a block. Contrary to "show{\textunderscore}stats" and "show{\textunderscore}config", "get{\textunderscore}block" returns the values in their binary form.

\dokubold{Arguments} module{\textunderscore}id, stats{\textunderscore}index

\dokubold{Returns} The block of data in binary representation. 


\dokutitleleveltree{get{\textunderscore}image}
\label{ee4063d08d26a6d5035ba0718b866b22}%% get_image
\index{DBG!get_image} Returns an image that is stored in a stats. Read \dokuitalic{Returns} for a description of the values returned.

\dokubold{Arguments} module{\textunderscore}id, stats{\textunderscore}index

\dokubold{Returns} The image in binary representation. The size of the returned block is of $width \cdot height \cdot \lceil\frac{bpp + 7}{8}\rceil$
. That means that a 20 x 20 black/white image ($bpp=1$
) will return 400 bytes. 


\dokutitleleveltree{set{\textunderscore}config}
\label{c1824a0ec7159a77cf4c0557c48cae44}%% set_config
\index{DBG!set_config} Sends a new config-value

\dokubold{Arguments} module{\textunderscore}id, config{\textunderscore}index, value value is in human-readable form.

\dokubold{Returns} "Reconfigured" on success 


\dokutitleleveltree{new{\textunderscore}list}
\label{321eff2dada7ce1d886ac39213550c19}%% new_list
\index{DBG!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.

\dokubold{Arguments} $module\_id_1$
, $stats\_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 \dokuitalic{read{\textunderscore}list} will contain a {value,time} pair.

\dokubold{Returns} The id of the list, in ascii


\dokutitleleveltree{read{\textunderscore}list}
\label{e908afb5398b7047293bfc18ec848b1c}%% read_list
\index{DBG!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.

\dokubold{Arguments} list{\textunderscore}id

\dokubold{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 "{\textbackslash}n".


\dokutitleleveltree{close{\textunderscore}list}
\label{4050d0805967ecd667d35249de489da2}%% close_list
\index{DBG!close_list} Finishes tracking of the values from this list.

\dokubold{Arguments} list{\textunderscore}id

\dokubold{Returns} OK or error on error. 


\dokutitleleveltree{process{\textunderscore}data}
\label{0eea9a8d5bb34042885cb1c78f1e1166}%% process_data
\index{DBG!process_data} Tells a module to immediatly start processing. If the module has inputs, all connected inputs will be activated before processing.

\dokubold{Arguments} module{\textunderscore}id

\dokubold{Returns} OK on success


\dokutitleleveltree{get{\textunderscore}profiling}
\label{30f45ef37ff615ac5ce466acb24a3a9e}%% get_profiling
\index{DBG!get_profiling} Returns all profiling-data from a module. The software-radio keeps track of the number of calls and the total execution-time of the following parameters: user-messages, data-processing and total time.

\dokubold{Arguments} module{\textunderscore}id

\dokubold{Returns} Three lines of profiling with the time spent and the number of calls seperated by a space. The numbers are 64-bit integers. The time spent is returned in $\mu$
s.


\dokutitleleveltree{ping}
\label{df911f0151f9ef021d410b4be5060972}%% ping
\index{DBG!ping} To test whether the software-radio is still running and replying to requests.

\dokubold{Arguments} none

\dokubold{Returns} "pong" 




\dokutitlelevelone{Signal Flow}
\label{4f016ecb0b15468688f1eb81b7a44e50}%% signal_flow
\label{4f016ecb0b15468688f1eb81b7a44e50}%%Start: signal_flow => /var/www/html/ipgwww/data/pages/signal_flow.txt
\index{Signal Flow|(} \label{cha: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}
\dokuitem  Common: the common signal-flow
\dokuitem  ICS-hardware: the signal-flow specific to the ICS-cards
\dokuitem  STM-hardware: the signal-flow specific to the STM-cards
\end{itemize}

\dokutitleleveltwo{Common}
\label{9efab2399c7c560b34de477b9aa0a465}%% common
\begin{figure}
\begin{center}
\includegraphics{/var/www/html/ipgwww/lib/plugins/tmp/texitimages/texitCQQyIE.ps}\end{center}
\caption{\label{fig:signal_common}The common part of the signal-flow}
\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 \dokuitalic{slot} which is a constant time-slice in the transmission.


\dokutitleleveltree{Transmitting}
\label{015d4b59bd7cdb1d43dca12cbfcd68b5}%% transmitting
The most common implementation starts with two blocks that have bits as output. The \dokuitalic{Source} may be anything, from a pseudo-random sequence to a part of a network-transmission.

 These bits go through a \dokuitalic{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}
\includegraphics{/var/www/html/ipgwww/lib/plugins/tmp/texitimages/texitjHmVEo.ps}\end{center}
\caption{\label{fig:qpsk-signal-space}QPSK signal space}
\end{figure}


\begin{figure}
\begin{center}
 		\includegraphics{/var/www/html/ipgwww/data/media/graphviz/a8e62e3704c8d6207994b627ab5622d2.ps}
 \end{center}
\caption{\label{fig:midamble}Position of the midamble}
\end{figure}


After the coding, the bits get \dokuitalic{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 \dokuitalic{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.


\dokutitleleveltree{Receiving}
\label{0639f5c0e2228ccdf3385f88f1579491}%% 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 \dokuitalic{Matched Filtering}, where the midamble from the sending chain is used to estimate the channel-parameters. Using these channel-parameters, one can improve the received quality of the signal. The output of this module is the filtered signal without the midamble. This module usually produces also information used by other modules, such as \dokuitalic{SNR} or \dokuitalic{amplitude} of the signal.

Now that the received signal is filtered, it is ready to be sliced. \dokuitalic{Slicing} denotes the fact of taking a hard decision on the received symbols. For a QPSK-signal, the quadrant of the symbol gives directly the two bits. If the signal-alphabet is bigger, one has to calculate the distances between the received symbol and all possible emitted symbols, and then taking the smallest distance. A hard decision is usually the worst thing to do. For example the LDPC-decoder takes the complex symbols directly from the matched filter and achieves much better results.

After the slicing, we have again a block of bits, which run through the \dokuitalic{Decoder}, where an algorithm tries to correct for transmission errors. As noted before, decoding on bits is not ideal, but it is what happens in most school-book examples\ldots{}

The decoder ouputs again a block of bits that should contain no errors anymore. This block can now be either used for the network-transmission, reception of an image, or just to count the number of residual errors, in order to evaluate a code/decoder-pair.


\dokutitleleveltwo{Hardware}
\label{3ca14c518d1bf901acc339e7c9cd6d7f}%% hardware
The hardwares job is to take the signal at it's sampling frequency, something around 1-10MHz, and to mix it so that it falls in the carrier-frequency, 1.9GHz, or 2.4-2.48GHz. In order to relieve the hardware of some very difficult filtering, it is important that the signal sent to the hardware does not occupy the whole sampling-frequency bandwith, but rather just a portion of it.

Furthermore it is important that, as the outgoing signal is filtered, as less as possible intersymbol interference is produced. For this reason, we apply a root-raised cosine filter, whose Fourier transform is the square root of the commonly used raised-cosine spectrum. If a root-raised cosine filter is used at both the transmitter and the receiver, the product of the  transfer functions will be a raised cosine that will give rise to an output having a minimal inter-symbol interference at the receiver.

The ICS- and STM-hardware differ mostly in two aspects:


\begin{itemize}
\dokuitem  Band while the ICS-hardware wants to have the signal in baseband, the STM-hardware needs the signal in passband
\dokuitem  Signal Unit the ICS-hardware works with complex samples, while the STM-hardware only works with real samples
\end{itemize}
 \begin{figure}
\begin{center}
\includegraphics{/var/www/html/ipgwww/lib/plugins/tmp/texitimages/texit4JPEu9.ps}\end{center}
\caption{\label{fig:hardware-baseband}The signal preparation for ICS}
\end{figure}
 \begin{figure}
\begin{center}
\includegraphics{/var/www/html/ipgwww/lib/plugins/tmp/texitimages/texit3G66xW.ps}\end{center}
\caption{\label{fig:hardware-passband}The signal preparation for STM}
\end{figure}


The figures \ref{fig:hardware-baseband} and \ref{fig:hardware-passband} depict the steps done to the signal from the fourier-transform point of view. The range of the fourier-transform has been chosen to be $-\frac{1}{2}..\frac{1}{2}$
, but one could have $-\frac{f}{2}..\frac{f}{2}$
 or $-\frac{\pi}{2}..\frac{\pi}{2}$
 without changing the meaning at all.


\dokutitleleveltree{ICS-hardware}
\label{446446d463e517efe6f80c3791ce6541}%% ics-hardware
\index{Hardware!ICS}

In figure \ref{fig:hardware-baseband}, you can see the preperation necessary for sending the signal to the ICS-hardware. The signal is first upsampled by a factor of two. This is done by inserting a zero in between two complex symbols.

Next we apply the lowpass RRC-filter and now we have a signal that occupies half the bandwith, but at double the symbol rate. Thus, we didn't loose information.

On the receiving side, exactly the contrary needs to be done: first we apply the RRC-filter, then we downsample by a factor of two. The filtering is necessary, as there might be some other signal next to ours. And, because the reception sample-rate is twice the symbol-rate, we have to downsample by a factor of two.


\dokutitleleveltree{Philips-hardware}
\label{5cd6be9d3d485aa7f1f520c81c4c0d67}%% philips-hardware
\index{Hardware!Philips}

The latest hardware that is not yet installed has been developed by Philips. It contains the A/D- and D/A-converters directly on the same board as the RF-part. The connection to the PC is made via two SCSI\dokufootnote{Small Computer System Interface}-cables, and the PCI-card only contains simple glue logic to put the data on the PCI-bus or to read it from there.

This hardware works at 1.9GHz and has a bandwith of 5MHz.


\dokutitleleveltree{STM-hardware}
\label{1793cae0983f21b2214d7a8c96518dac}%% stm-hardware
\index{Hardware!STM}

Looking at figure \ref{fig:hardware-passband}, you can see that for the STM-hardware, we need to upsample by a factor of four. The filter chosen for the pulse-shaping is a passband-filter, that has a bandwith of 1/4.

Because the hardware accepts only real samples, we can't keep the signal at baseband, as a loss of the signal would happen. You can see that by taking the real-part of the signal, it gets mirrored at the axis. If you do this with a baseband signal, information loss occurs.

These three operations are done using advanced MMX-operations that manage to take advantage of the special structures of the filters and the signal. \index{Signal Flow|)} 




\dokutitlelevelone{Important Modules}
\label{6abb51394e80f74c506056160ad1309c}%% important_modules
\label{6abb51394e80f74c506056160ad1309c}%%Start: important_modules => /var/www/html/ipgwww/data/pages/important_modules.txt
In this chapter you'll learn about some of the most important modules in the software-radio. They represent the basic functionality and should be known by everyone that wants to handle the software-radio.


\dokutitleleveltwo{STFA}
\label{adebc2516025b7bd604b0cfcfa740885}%% stfa
\label{sec:stfa}

\index{STFA} STFA stands for Slot To Frame Allocator. Its main purpose is to map the RX- and TX-slots to the correct moment in time. First of all you need to understand the principles of a slotted TDD transmission using frames. In figure \ref{fig:stfa_frames_slots} you can see a transmission of 3 frames. Each frame takes the same amount of time. Normally the frame-structure stays the same during the transmission. Of course this wouldn't be the case in a multi-user environment, where a frame contains the structure of the up- and downlink slots, which would change during connection and disconnection of users.

\begin{figure}
\begin{center}
\includegraphics{/var/www/html/ipgwww/lib/plugins/tmp/texitimages/texiteoaPIO.ps}\end{center}
\caption{\label{fig:stfa_frames_slots}The frames and slots}
\end{figure}


The STFA represents this frame-structure. It is a module with  inputs and  outputs, where  is the number of slots per frame. The purpose of the STFA is to calculate the slots so that they are sent at the correct moment in time. To understand figure \ref{fig:stfa_in_out} correctly, it helps to imagine yourself the STFA as a representation of the channel. So the inputs of the STFA are the inputs to the channel, which corresponds to the TX-part. The outputs of the STFA are what comes out of the channel, which is the RX-part.

\begin{figure}
\begin{center}
\includegraphics{/var/www/html/ipgwww/lib/plugins/tmp/texitimages/texitTnOJEH.ps}\end{center}
\caption{\label{fig:stfa_in_out}Inputs and outputs of the STFA}
\end{figure}


Internally, the STFA has two large sample-buffers that hold one complete frame in memory. One buffer is read continously \dokufootnote{the transmission is
done in blocks using DMA} from by the D/A converter, while the other buffer is written to continously \dokufootnote{the transmission is
done in blocks using DMA} by the A/D converter. For this reason, it is important that the result of one slot is computed before the D/A converter needs it. It is also important that a RX-slot is processed before the next frame.


\dokutitleleveltree{Synchronisation}
\label{85ceb46695acb5dfcc7a806904a25365}%% synchronisation
\label{subsec:synchronisation} A common problem in a slotted TDD-environment is the synchronisation of two stations. If we consider two participants in a communication, called BS and MS\dokufootnote{Microsoft} (for Base Station and Mobile Station), one has to define at what instant in time the first frame starts. If we call this time-instant $t_{frame}(0)$
, then all consecutive frames will start at $t_{frame}(n) = t_{start} + n d_{frame}$
 where  is a positive integer and $d_{frame}$
 is the time-duration of one frame. This also defines all slots, as  $t_{slot}(m) = t_{frame}(n) + m d_{slot}$
 with $d_{slot}$
 the time-duration of one slot and $0<m<slots$
. 

We can't know beforehand $t_{frame}(0)$
, and also $d_{frame}$
 is only known up to a certain $\delta t$
, because of clock-drifts between the two stations. One solution is to send a synchronisation-signal in slot 0, so that one can know $t_{slot}(0)$
 for every frame. Then we can find $t_{slot}(m)$
 for all the other slots of the frame, supposing that the error in $d_{slot}$
 is negligible when calculating the time-instants of one slot.

\begin{figure}
\begin{center}
\includegraphics{/var/www/html/ipgwww/lib/plugins/tmp/texitimages/texitIM6CEB.ps}\end{center}
\caption{\label{fig:stfa_typical}A typical set-up of the STFA}
\end{figure}


This setup is shown in figure \ref{fig:stfa_typical}. In a real system, the MS\dokufootmark{3} starts out with synchronisation modules attached to all its STFA-outputs. The reason for this is that upon startup, we don't have any information about $t_{slot}(0)$
, so we have to expect the synchronisation-signal on any slot. Once the synchronisation-signal is found on a given slot, the buffers are adjusted so that the synchronisation-signal falls into $slot_0$
. Then, each time $slot_0$
 is received, the buffer is adjusted again, so that all $t_{slot}(m)$
 are accurate and in synchronisation with the BS again.


\dokutitleleveltree{Important Parameters}
\label{c58082b3cfc77c3c5898176deb48e933}%% important_parameters
There are three groups of parameters in the STFA:


\begin{itemize}
\dokuitem  Structural which define the size of the different parts of the STFA
\dokuitem  Timing everything that got to do with preparation of slots and synchronization
\dokuitem  RF the parameters of the RF-part are also reflected in the STFA
\end{itemize}

\dokutitlelevelfour{Structural}
These are quite important, as they define the basic structure and size of the STFA. You can't change these parameters once the STFA has been started, as the DMA-transfer would be disturbed greatly by this. An overview of the parameters is given in figure \ref{fig:stfa_size_params}.

\begin{figure}
\begin{center}
\includegraphics{/var/www/html/ipgwww/lib/plugins/tmp/texitimages/texitnQPtPw.ps}\end{center}
\caption{\label{fig:stfa_size_params}The different size-parameters}
\end{figure}


The \dokuitalic{blocks{\textunderscore}per{\textunderscore}slot} parameter has a unit of 128 symbols. By taking the default value of 20, this gives a slot-length of 2560 symbols. Substracting the guard-period, we get a useable slot-length of 2470 symbols.

To make things even more complicate, the total number of \dokuitalic{blocks} has to be a multiple of 16. This is due to the fact that the DMA-transfer is done in blocks with a size of 16 * 128 symbols \dokufootnote{This is defined in
Base{\textbackslash}/Antenna{\textbackslash}/ICS/ics{\textunderscore}dev.h}. Taking a smaller block-size for the DMA-transfer would result in more interrupts and thus a higher system-load.

As we have a TDD-system, TX and RX slots are stacked up in time. Without any special handling, the RF-system would have to be able to switch off the transmit-chain from one symbol to another. Because this is very difficult to do, a \dokuitalic{guard-period} has been inserted. During this time, the state of the RF-cards is not defined, and no useful data is transmitted.


\dokutitlelevelfour{Timing}
Usually you don't have to change these parameters. They are taken into account by the synchronisation-macro module.


\dokutitleleveltree{Attaching Chains}
\label{0ee4bd1a5c3946e216846a3d858abca9}%% attaching_chains
The STFA on its own doesn't do anything. The mode of operation and the kind of mapping done over the air is defined by attaching chains to it. If a chain is attached to an input of the STFA, we talk about a transmit-chain, or TX-chain. A receive-chain or RX-chain is attached to the output of the STFA.

\begin{figure}
\begin{center}
\includegraphics{/var/www/html/ipgwww/lib/plugins/tmp/texitimages/texitgzuVPs.ps}\end{center}
\caption{\label{fig:stfa_tx_rx_example}Two transmit and one receive-chain as an example}
\end{figure}


In figure \ref{fig:stfa_tx_rx_example} you see a picture of some example-chain. In the middle is the STFA that is responsible to alert all modules as soon as there is some data to proceed. Looking at the RX-chain, you see that it is very simple for the STFA to know when to alert the RRC-module of the chain. The right moment is when this slot has been received.

For the TX1-chain, the right moment to alert the source-module is $t_{alert}=t_{slot}(0)-d_{calc_chain_tx1}$
. Unfortunatly the $d_{calc_chain_tx1}$
 is not known in advance and might change during the run of the software-radio. One way to tackle this problem is to put an upper time-limit on the calculation-duration, and call the top-module that much in advance. In the actual STFA-implementation, $d_{calc_chain_tx_max}=2*d_{slot}$
, so that the first module of the TX1-chain is called at the beginning of slot 0.

Another problem arises when we have constructs as in the TX2-chain \dokufootnote{The two branches may also fall into two different STFAs}. Although it is not optimal (See \ref{future_stfa_chains}), we applied the same reasoning as with the TX1-chain, that is, we call the top module of the TX2-chain two slots in advance. The disadvantage is, that the whole chain has to finish in the time $2*d_{slot}$
.


\dokutitlelevelfour{Overcoming the Time-Limits}
In an ideal setup, you'll be able to calculate every slot in a frame fast enough, so that it can be sent on time over the air. Unfortunatly, this is not always the case. Sometimes you want to trade in some of the real-time with the possibility to do some more calculations than the time allows. The problem is different on the sending- and on the receiving side.

The only time you'd want to send a slot that takes a very long time to calculate is when you want to do repeated measurements on the slot. So what you can do is to calculate the slot once, and then send it again and again. You can do this by setting the notice-point not to the top-module, but rather to the RRC-module only. Like this only the pulse-shape will be done, taking care of an eventual desynchronisation between the two radios \dokufootnote{Remember that the
MS\dokufootmark{3} moves in time}.

On the receiver side, the only reason for taking more than the allocated time is about the same. But you may easily take up more time than $2*d_{slot}$
, if the total amount of all receiving chains is not bigger than one frame. If this might be the case, then you can use the following command:


\small
\begin{verbatimtab}
make_thread( rrc_id );
\end{verbatimtab}
\normalsize
This means that every time the STFA has data that needs to be processed, it checks whether the chain is still working, and only notifies the top-module, if no work is done. If the chain is still working, the STFA doesn't send the request, and waits for the next frame to check back again.

Here at EPFL we use these two techniques to measure code-qualities, especially LDPC-coding schemes. It is important to us that we get an actual transmission, but analyzing 10 slots per second is good enough for our case. 

 


\dokutitlelevelone{Subsystems}
\label{23dd63f2ae75bad0aa94aa78fda83dc0}%% subsystems
\label{71f7b1ba9fdbe73d19d4343685d7acad}%%Start: subsystem => /var/www/html/ipgwww/data/pages/subsystem.txt
 The software-radio has a reception and a transmission part. Each one of these has its specialities and quirks. Here I list the names used in programming, the restrictions and how they come across. Only the reception-part is treated in this document, as the transmission-part is quite simple.


\dokutitleleveltwo{Nyquist}
\label{53ddc797d8904f9366b1ea3287f6309f}%% nyquist
 It is very important to understand the implication of Nyquists theorem for this reception-chain. Nyquist wrote that the sampling-frequency must be twice the bandwith of the signal to sample. He also described the aliasing that happens if you sample a signal that is out of this bound. For the reception-part of the software-radio, we rely on this aliasing to capture a signal at an intermediate frequency of 70MHz using a sampling-frequency of 100MHz. In a most general way, given the parameters:


\begin{lyxlist}{00.00.0000}

\item [fi{\textunderscore}rx]the intermediate frequency


\item [wi{\textunderscore}rx]the intermediate used bandwith


\item [f{\textunderscore}adc]the sampling-frequency of the analog-to-digital converter

\end{lyxlist}

then f{\textunderscore}adc must be chosen so that $$\frac{f_ adc}{2}N\notin\left[fi_ rx-\frac{wi_ rx}{2}, fi_ rx+\frac{wi_
rx}{2}\right]$$
 is fulfilled. Else we get an overlapping of the aliased signal and we loose information.

For the software-radio, $fi_rx=70MHz$
, $wi_rx=20MHz$
, $f_adc=100MHz$
, which fullfills the above equation.


\dokutitleleveltwo{Reception-chain}
\label{24a9af8ad85f475e29c6cbb5f8984e89}%% reception-chain
 \begin{figure}
\begin{center}
\includegraphics{/var/www/html/ipgwww/lib/plugins/tmp/texitimages/texitXx6eir.ps}\end{center}
\caption{\label{cap:Reception-chain}Reception-chain}
\end{figure}
 \begin{figure}
\begin{center}
\includegraphics{/var/www/html/ipgwww/lib/plugins/tmp/texitimages/texitGdqtRq.ps}\end{center}
\caption{\label{cap:DDC-chain}The whole chain and the most important part of it}
\end{figure}


The different parameters of fig.\ref{cap:Reception-chain} and fig.\ref{cap:DDC-chain}, their boundaries, and a short description:


\begin{lyxlist}{00.00.0000}

\item [f{\textunderscore}rf][2300..2500]MHz\dokufootnote{Megahertz}, the transmission-frequency


\item [attn{\textunderscore}rx][0-41]dB, the attenuation of the Rx-chain (0 gives stronges output, 41 gives weakest)


\item [f{\textunderscore}adc][1-100]MHz\dokufootmark{1}, the sampling frequency of the ADC.


\item [fi{\textunderscore}rx][1-500]MHz\dokufootmark{1}, the intermediate frequency. Every frequency above $\frac{f_ adc}{2}$
 will be attenuated due to the sinc of the ADC.


\item [fs{\textunderscore}rx][0-$\frac{f_ adc}{8}$
]MHz\dokufootmark{1}, the final sampling frequency (the DDC does down-sampling). Contrary to f{\textunderscore}adc, fs{\textunderscore}rx is measured in complex samples.


\item [w{\textunderscore}rx][0.08-0.75], the portion of the final sampling frequency fs{\textunderscore}rx which is not cut off by the DDC filters.

\end{lyxlist}

 \begin{comment}
How is the bandwith related to fs_rx? Is it 0.08-0.75 or 0.16 - 1.5?
\end{comment} 


\begin{lyxlist}{00.00.0000}

\item [sig{\textunderscore}type]{ SIG{\textunderscore}COMPLEX{\textunderscore}ICS, SIG{\textunderscore}S16 } for FPGA{\textunderscore}DEFAULT\\  { SIG{\textunderscore}COMPLEX{\textunderscore}S16 } for FPGA{\textunderscore}S16

\end{lyxlist}


\dokutitleleveltwo{More detail}
\label{3df268da78bf780dc1c2690f0ad77c6a}%% more_detail
 The final sampling frequency is limited by the use of the DDCs in the card. A simplified structure of the DDCs can be seen in fig.\ref{cap:DDC-chain}. Due to internal limitations, the smallest useable decimation factor of the DDCs is 8, and the highest is 4096. For more detail, see the Graychip-documentation on page 11, 3.4.2 and references.


\dokutitleleveltree{w{\textunderscore}rx}
\label{dc3788f5238b0e4c2d4993ed54fb0e30}%% w_rx
 This parameter is also dependant on the DDC-chips. In fig.\ref{cap:DDC-chain} this is simplified by a \dokuitalic{Filtering} block. The DDC itself does implement this filtering with two filters, called \dokuitalic{cfir} and \dokuitalic{ffir}. The exact nature of these filters is subject to a subsequent work and thus only pre-calculated filters have been used. This is why the bandwith can only be one of {0.085, 0.17, 0.34, 0.40, 0.50, 0.75}.

Another point here: the filters in \dokuitalic{filters.c} are defined for twice this bandwith. This is because of the internal workings of the DDCs and can only be understood through a thorough study of the Graychip-documentation, see also the document about the DDC by Ignace.


\dokutitleleveltree{sig{\textunderscore}type}
\label{14470ce2aed051316b9d37d96099f24b}%% sig_type
 The signal-types are defined for the software-radio and can be chosen to be one of the following. The choice of the signal-type influences also whether the DDCs are used or not.


\begin{lyxlist}{00.00.0000}

\item [SIG{\textunderscore}COMPLEX{\textunderscore}ICS]is the standard mode of the ICS-card. In this mode, DDCs are enabled and the signal is outputted in baseband.


\item [SIG{\textunderscore}S16]bypasses the DDCs and transfers the direct output of the ADCs. This has been tested with one ADC only. It is useful for processing high-bandwith signals.


\item [SIG{\textunderscore}COMPLEX{\textunderscore}S16]is only possible with a re-programmed FPGA on the ICS-cards. DDCs are enabled, only one channel is transmitted, but not in the SIG{\textunderscore}COMPLEX{\textunderscore}ICS format that takes 128bits per sample, but in a more simple SIG{\textunderscore}COMPLEX{\textunderscore}S16 format, that only takes 32bits per complex sample, thus allowing 4 times more storage.

\end{lyxlist}




\dokutitlelevelone{Interface}
\label{8eb58dd5e328e978169c7b0cbd30d43f}%% interface
\label{8eb58dd5e328e978169c7b0cbd30d43f}%%Start: interface => /var/www/html/ipgwww/data/pages/interface.txt
 The following files have been rewritten:

 


\small
\begin{verbatimtab}

Include/antenna.h
Base/Antenna/ICS/*
Base/Antenna/Common/antenna.c

\end{verbatimtab}
\normalsize
 \begin{comment}
And all files that ask for a ICS-card!
\end{comment} 

In table \ref{tab:commands} you can see the newly defined commands.


\dokutitleleveltree{New commands defined}
\label{6ecf79d3c554ca379040188ff4e95f30}%% new_commands_defined
\label{tab:commands}

%% Table analyse:
%%    Numrows: 13
%%    Most Long row size: 113
%%    Choose table mode: tabularx
\begin{figure}[h]
\begin{tabularx}{\dokutabularwidth}{|X|X|}%% 102 | X | 
\hline
{\dokuheadingstyle{\color{dokuheadingcolor} Name \normalcolor}}&{\dokuheadingstyle{\color{dokuheadingcolor} Short description \normalcolor}}\\ 
\hline
{ \dokumonospace{swr{\textunderscore}ant{\textunderscore}ics{\textunderscore}init} }&{ Initialises the ics-cards, should be called first }\\ 
\hline
{ \dokumonospace{swr{\textunderscore}ant{\textunderscore}ics{\textunderscore}get{\textunderscore}fs{\textunderscore}rx} }&{ Returns the real sampling-frequency }\\ 
\hline
{ \dokumonospace{swr{\textunderscore}ant{\textunderscore}ics{\textunderscore}get{\textunderscore}fs{\textunderscore}tx} }&{ Returns the real sampling-frequency }\\ 
\hline
{ \dokumonospace{swr{\textunderscore}ant{\textunderscore}ics{\textunderscore}rx} }&{ Sets the bandwith and the if-frequency }\\ 
\hline
{ \dokumonospace{swr{\textunderscore}ant{\textunderscore}ics{\textunderscore}rx{\textunderscore}freq} }&{ Sets the if-frequency of the reception, also while the radio is running }\\ 
\hline
{ \dokumonospace{swr{\textunderscore}ant{\textunderscore}ics{\textunderscore}tx} }&{ Sets the if-frequency of the transmission, also while the radio is running }\\ 
\hline
{ \dokumonospace{swr{\textunderscore}ant{\textunderscore}ics{\textunderscore}clk} }&{ Sets the speed of the clock-reference, as well as the multiplication-factor of the DACs }\\ 
\hline
{ \dokumonospace{swr{\textunderscore}ant{\textunderscore}ics{\textunderscore}start} }&{ Starts the transmission }\\ 
\hline
{ \dokumonospace{swr{\textunderscore}ant{\textunderscore}ics{\textunderscore}stop} }&{ Stops the transmission }\\ 
\hline
{ \dokumonospace{swr{\textunderscore}ant{\textunderscore}ics{\textunderscore}io} }&{ Returns the time left to reach a certain position in the reception }\\ 
\hline
{ \dokumonospace{swr{\textunderscore}ant{\textunderscore}ics{\textunderscore}set{\textunderscore}synth} }&{ Sets the synthesizer on the RF-card }\\ 
\hline
{ \dokumonospace{swr{\textunderscore}ant{\textunderscore}ics{\textunderscore}write{\textunderscore}ddcs} }&{ Writes the calculated values to the DDCs, can't be called while the radio is running! }\\ 
\hline
\end{tabularx}
\end{figure}

 \newpage


\dokutitleleveltwo{int swr{\textunderscore}ant{\textunderscore}ics{\textunderscore}init( fs{\textunderscore}rx, fs{\textunderscore}tx, ch{\textunderscore}rx, ch{\textunderscore}tx, sig{\textunderscore}type );}
\label{fe984c51aa3925f30faa85220efd9a71}%% int_swr_ant_ics_init_fs_rx_fs_tx_ch_rx_ch_tx_sig_type
This is the first function to call to initialise the cards. This function can only be called when the cards are not running, as some very basic parameters are defined in here.


\dokutitleleveltree{fs{\textunderscore}rx}
\label{30527d188a1c1cc1372f85a0942c8e8f}%% fs_rx
 \dokubold{Type}: double

\dokubold{Description:}

sampling frequency for the reception, in Hz. Must be between 10kHz and 3MHz. The sampling-frequency on the reception has some constraints, described in the function \dokuitalic{swr{\textunderscore}ant{\textunderscore}ics{\textunderscore}clk}. This sampling-frequency is given in complex samples, so that a sampling frequency of 10MHz gives a theoretical bandwith of 10MHz! See also \dokuitalic{swr{\textunderscore}ant{\textunderscore}ics{\textunderscore}rx}


\dokutitleleveltree{fs{\textunderscore}tx}
\label{e8cf252e1acc8c5f8d257747b59151a6}%% fs_tx
 \dokubold{Type}: double

\dokubold{Description:}

sampling frequency for the transmission, in Hz. Must be between 10kHz and 3MHz. The sampling-frequency of the transmission has some constraints that are described in the function \dokuitalic{swr{\textunderscore}ant{\textunderscore}ics{\textunderscore}clk}. This frequency is in complex samples! Please be aware that the DACs have an in-built filter that cuts the useful signal to about 75\% of the bandwith of fs{\textunderscore}tx. So if fs{\textunderscore}tx is 1MHz, the useful bandwith is about 750kHz.


\dokutitleleveltree{ch{\textunderscore}tx}
\label{783e84eae940cf61c72d2517f9b93055}%% ch_tx
 \dokubold{Type}: uint

\dokubold{Description:}

how many rx-channels, between 0 and 4 |


\dokutitleleveltree{ch{\textunderscore}tx}
\label{783e84eae940cf61c72d2517f9b93055}%% ch_tx
 \dokubold{Type}: uint

\dokubold{Description:}

how many tx-channels, between 0 and 4


\dokutitleleveltree{sig{\textunderscore}type}
\label{14470ce2aed051316b9d37d96099f24b}%% sig_type
 \dokubold{Type}: swr{\textunderscore}signal{\textunderscore}type{\textunderscore}t

\dokubold{Description:}

the desired type of the rx-channels, it depends on the program in the FPGA. A version exists for a one-channel, 32-bit complex reception mode (16bits real and 16bits imaginary), using the DDCs but allowing for a longer aquisition time. In this mode, \dokuitalic{ch{\textunderscore}tx} must be 0 and \dokuitalic{ch{\textunderscore}rx} 1. The different signal types correspond to the following: 


\begin{lyxlist}{00.00.0000}

\item [SIG{\textunderscore}COMPLEX{\textunderscore}ICS]is the signal used by most of the radio-systems, as it allows to use the DDC and works with complex signals on the reception path


\item [SIG{\textunderscore}S16]is used for the 802.11. Here the DDCs are completely bypassed and raw ADC-material is received.

\item [SIG{\textunderscore}S32]not implemented yet: DDCs work in wideband real-mode only


\item [SIG{\textunderscore}COMPLEX{\textunderscore}S16]uses the modified FPGA to implement a 1-channel 32 to 16 bit conversion, including the DDCs. Used for GPS-reception.

\end{lyxlist}

 After this function has been called, everything is set up so that \dokuitalic{swr{\textunderscore}ant{\textunderscore}init} can be called. All other funtions defined in here are only for more special needs.

\dokuitalic{swr{\textunderscore}ant{\textunderscore}ics{\textunderscore}init} calls \dokuitalic{swr{\textunderscore}ant{\textunderscore}ics{\textunderscore}clk( 100e6, 4, 50e6 )} which initialises the multipliers on the ICS-cards.

fs{\textunderscore}rx and fs{\textunderscore}tx have to meet certain criterias, so the final values may differ from the chosen ones! To get the real values, use the functions \dokuitalic{swr{\textunderscore}ant{\textunderscore}ics{\textunderscore}get{\textunderscore}fs{\textunderscore}rx} as well as the function \dokuitalic{swr{\textunderscore}ant{\textunderscore}ics{\textunderscore}get{\textunderscore}fs{\textunderscore}tx}, which return the re-calculated values.

 \newpage 


\dokutitleleveltwo{double swr{\textunderscore}ant{\textunderscore}ics{\textunderscore}get{\textunderscore}fs{\textunderscore}rx( void );}
\label{fd796ad192a2c276dc56926f96198b7f}%% double_swr_ant_ics_get_fs_rx_void

\dokutitleleveltwo{double swr{\textunderscore}ant{\textunderscore}ics{\textunderscore}get{\textunderscore}fs{\textunderscore}tx( void );}
\label{923f6bf56d826a6ce0d0714fa1e78772}%% double_swr_ant_ics_get_fs_tx_void
 These function get the actual sampling frequency as calculated by \dokuitalic{swr{\textunderscore}ant{\textunderscore}ics{\textunderscore}clk}. They return the actual frequency in Hz, which may differ from the settings, because of the limitations of the cards.


\dokutitleleveltwo{void swr{\textunderscore}ant{\textunderscore}ics{\textunderscore}rx( ch, fc, W );}
\label{5aa49d1caaaab337cc82e1f064fd6664}%% void_swr_ant_ics_rx_ch_fc_w

\dokutitleleveltree{ch}
\label{d88fc6edf21ea464d35ff76288b84103}%% ch
 \dokubold{Type}: int

\dokubold{Description:} The affected channel, 0-3


\dokutitleleveltree{fc}
\label{e05fe30750d3ea262a610d17ebc07019}%% fc
 \dokubold{Type}: double

\dokubold{Description:} The new center-frequency


\dokutitleleveltree{W}
\label{f1290186a5d0b1ceab27f4e77c0c5d68}%% w
 \dokubold{Type}: double

\dokubold{Description:} The bandwith of the final samples that contain data, relative to fs{\textunderscore}rx set by swr{\textunderscore}ant{\textunderscore}ics{\textunderscore}init. W $\in$
 {0.085, 0.17, 0.34, 0.5, 0.75}. If a non-existant bandwith is selected, the next-higher (or highest available) will be chosen.

 fc is re-calculated to fit into $[0..\frac{fs_ rx}{2}]$
, using the availability of different Nyquist windows. First it is converted relative to the sampling-frequency: 

$$f=\frac{fc}{fs_rx}$$


Then it is converted using: 

$$f_p=\frac{1-\left|\left(f-\lfloor f \rfloor \right ) * 2 - 1 \right |}{2}$$


f{\textunderscore}p is calculated with 31 bits precision. For a fs{\textunderscore}rx of 100MHz this gives a precision of $\frac{1}{20}$
Hz.


\dokutitleleveltwo{void swr{\textunderscore}ant{\textunderscore}ics{\textunderscore}rx{\textunderscore}freq( ch, fc );}
\label{268df8a51d124c8f52f2da6e5e79db96}%% void_swr_ant_ics_rx_freq_ch_fc
 Function to set only the intermediate-frequency of the reception-part.


\dokutitleleveltree{ch}
\label{d88fc6edf21ea464d35ff76288b84103}%% ch
 \dokubold{Type}: int

\dokubold{Description:} The affected channel, 0-3


\dokutitleleveltree{fc}
\label{e05fe30750d3ea262a610d17ebc07019}%% fc
 \dokubold{Type}: double

\dokubold{Description:} The new intermediate-frequency, see also the function swr{\textunderscore}ant{\textunderscore}ics{\textunderscore}rx

Because it is very difficult to re-program the DDC-chip while the software-radio is running, this function has been written to only re-program the intermediate-frequency and nothing else. This function only calculates the new value to be programmed in the DDC-chip. The final programmation of the chip is done in the DMA-interrupt so that the transmission is not interrupted.


\dokutitleleveltwo{void swr{\textunderscore}ant{\textunderscore}ics{\textunderscore}tx( ch, fi{\textunderscore}tx );}
\label{99e682d95700562b0243e2ef2b70cb94}%% void_swr_ant_ics_tx_ch_fi_tx
 This sets the intermediate frequency 'fi{\textunderscore}tx' for the tx-channel. For the re-calculation of the intermediate frequency, see \dokuitalic{swr{\textunderscore}ant{\textunderscore}ics{\textunderscore}rx}.

This function can be used without problems during runtime.


\dokutitleleveltree{ch}
\label{d88fc6edf21ea464d35ff76288b84103}%% ch
 \dokubold{Type}: int

\dokubold{Description:} The affected channel, 0-3


\dokutitleleveltree{fi{\textunderscore}tx}
\label{3c4aea7b2bbe16b68955606a16f7ccfd}%% fi_tx
 \dokubold{Type}: double

\dokubold{Description:} center-frequency, in Hz


\dokutitleleveltwo{void swr{\textunderscore}ant{\textunderscore}ics{\textunderscore}clk( f{\textunderscore}adc dac{\textunderscore}mult, f{\textunderscore}dac );}
\label{79ec0feba565daec73ffec6f887195ed}%% void_swr_ant_ics_clk_f_adc_dac_mult_f_dac
 The ICS-cards usually are clocked by an external 50MHz-clock. If you set a new clock-frequency, fs{\textunderscore}rx and fs{\textunderscore}tx are re-calculated and might differ. A frequency set with \dokuitalic{swr{\textunderscore}ant{\textunderscore}ics{\textunderscore}init} might be possible with f{\textunderscore}dac=50MHz, but not fit correctly into f{\textunderscore}dac=25MHz!


\dokutitleleveltree{f{\textunderscore}adc}
\label{a5bc4d6a0be649f08b3e39ae04e0b3f3}%% f_adc
 \dokubold{Type}: double

\dokubold{Description:} the external frequency in Hz


\dokutitleleveltree{dac{\textunderscore}mult}
\label{ca785d7ae9357efaae33172b1d236482}%% dac_mult
 \dokubold{Type}: int

\dokubold{Description:} the multiplier. One of { 1, 4..16 }


\dokutitleleveltree{f{\textunderscore}dac}
\label{2c59eedc572f0ec2e98e6b1eb6c2cc52}%% f_dac
 \dokubold{Type}: double

\dokubold{Description:} the external frequency in Hz


\dokutitleleveltwo{void swr{\textunderscore}ant{\textunderscore}ch{\textunderscore}start( void );}
\label{99db4a60a6a5eaca73114e8f79706554}%% void_swr_ant_ch_start_void
 Here the channel begins to send/receive data. All initialised antennas begin at once to send/receive.


\dokutitleleveltwo{void swr{\textunderscore}ant{\textunderscore}ch{\textunderscore}stop( void );}
\label{7bfb4b74dbdb174b1dacf5438d921c20}%% void_swr_ant_ch_stop_void
 Here the channel interrupts sending/receiving data. It may be that later on another transmission starts.


\dokutitleleveltwo{int swr{\textunderscore}ant{\textunderscore}ch{\textunderscore}io( slot );}
\label{0985a4567b043e5dbbff0608c3a80637}%% int_swr_ant_ch_io_slot
 This function returns the time to wait so that the next slot will be sent/received.


\dokutitleleveltree{slot}
\label{5e97994ed38a2b2f984f3b2b75012bf8}%% slot
 \dokubold{Type}: int

\dokubold{Description:} read/write up to this block


\dokutitleleveltree{return}
\label{e70c4df10ef0983b9c8c31bd06b2a2c3}%% return
 \dokubold{Type}: int

\dokubold{Description:} The time in micro-seconds ($10^{-6}$
) to wait


\dokutitleleveltwo{void swr{\textunderscore}ant{\textunderscore}ch{\textunderscore}set{\textunderscore}synth( ch, RF, side);}
\label{f6ab0cb22f6739a6978ef9e17a123a9c}%% void_swr_ant_ch_set_synth_ch_rf_side
 Sets the synthesizer on a given RF-board. Due to some constraints, the RF-boards take quite some time to behave stable in a new frequency. This is in the order of a couple of ms.


\dokutitleleveltree{ch}
\label{d88fc6edf21ea464d35ff76288b84103}%% ch
 \dokubold{Type}: int

\dokubold{Description:} The affected channel, 0-3


\dokutitleleveltree{RF}
\label{bea2f3fe6ec7414cdf0bf233abba7ef0}%% rf
 \dokubold{Type}: double

\dokubold{Description:} The frequency in Hz: [2.3..2.5] * $10^{9}$



\dokutitleleveltree{side}
\label{9c62ad1fc551d04b815c8573285b65b2}%% side
 \dokubold{Type}: int

\dokubold{Description:} low- or high-injection:


\begin{lyxlist}{00.00.0000}

\item [0]Auto


\item [1]low-injection


\item [2]high-injection

\end{lyxlist}

\newpage


\dokutitleleveltwo{void swr{\textunderscore}ant{\textunderscore}ch{\textunderscore}set{\textunderscore}freq{\textunderscore}diff( ch, freq{\textunderscore}diff);}
\label{30bb68262528241c4a828a17d5643c69}%% void_swr_ant_ch_set_freq_diff_ch_freq_diff
 As described in the function \dokuitalic{swr{\textunderscore}ant{\textunderscore}ics{\textunderscore}tx}, the value for the intermediate tx-frequency has a resolution of 32bits. With this function, you can set an offset to the 'official' value.


\dokutitleleveltree{ch}
\label{d88fc6edf21ea464d35ff76288b84103}%% ch
 \dokubold{Type}: int

\dokubold{Description:} The affected channel, 0-3


\dokutitleleveltree{frec{\textunderscore}diff}
\label{8eb5aa7101d8293a4570cfd3c89ef6bc}%% frec_diff
 \dokubold{Type}: long int

\dokubold{Description:} An offset to the set value. The step is $\frac{fs_tx}{2^{32}}$
, where fs{\textunderscore}tx includes an eventual multiplicator (usually 4).


\dokutitleleveltwo{write{\textunderscore}ddcs( void );}
\label{2777f832d72ca8a9dd7b54dff7d7a1e8}%% write_ddcs_void
 A function called \dokuitalic{ics554{\textunderscore}ddc{\textunderscore}set{\textunderscore}cic} is used to set the decimation to the desired value. The main problem is the calculation of the attenuation of the signal. This function has been tested for a wide range of decimations and should work without problems. 




\dokutitlelevelone{FPGA}
\label{a5643066c7a784ec29b50db0361ec90f}%% fpga
\label{a5643066c7a784ec29b50db0361ec90f}%%Start: fpga => /var/www/html/ipgwww/data/pages/fpga.txt
\label{sec:FPGA}

For the work on the software-radio, we have two versions of the FPGA:


\begin{lyxlist}{00.00.0000}

\item [STD]which is the standard off-the-shelf version, that works for SIG{\textunderscore}COMPLEX{\textunderscore}ICS and SIG{\textunderscore}S16


\item [GPS]which is used for the GPS SIG{\textunderscore}COMPLEX{\textunderscore}S16

\end{lyxlist}

Both of these modes can be programmed using a simple Tool. This can be found in the directory FPGA. If all you want is to reprogram the FPGA, here is how to proceed: 


\begin{enumerate}\dokuitem  cd into the directory
\dokuitem  ./compile
\dokuitem  program :
\begin{itemize}
\dokuitem  for the GPS-version:\\  ./program gps
\dokuitem  for the standard-version:\\  ./program std
\end{itemize}

\end{enumerate}
 Of course, if you want to switch back and forth between versions, you don't have to enter the "./compile"-command every time.


\dokutitleleveltwo{Directories}
\label{bd1e333d1166f18893b2bbeba10229a3}%% directories
 
\begin{lyxlist}{00.00.0000}

\item [Module]The kernel-module to talk to the ics554-card


\item [Program]The actual programmer for the FPGA


\item [Api]The Application Programming Interface, the glue between \dokuitalic{Module} and \dokuitalic{Program}


\item [inc]The include-files necessary

\end{lyxlist}

All these files are nearly identical to the software delivered on the ICS-CDs of the software-development pack. The only change has been done to the \dokuitalic{Program}, so that it accepts the command-line switches and doesn't wait for a key.


\dokutitleleveltwo{Testing the version}
\label{bb2dbe58be266ca852a85bd8d17908d7}%% testing_the_version
\label{subsec:fpga-version}

Before running the radios it is a good idea to verify the version of the program in the FPGA. This can be done by running the following program:


\small
\begin{verbatimtab}

cd
$SRADIO/Test/FPGA
make test

\end{verbatimtab}
\normalsize
This will tell you whether the actual program supports either STD or GPS mode. 

 


\dokutitlelevelone{Tidbits}
\label{77521cac97140534b4f5eebfd1f61417}%% tidbits
\label{77521cac97140534b4f5eebfd1f61417}%%Start: tidbits => /var/www/html/ipgwww/data/pages/tidbits.txt

\dokutitleleveltwo{DMA-considerations}
\label{7de8c158c21d5f79daec6876ae256110}%% dma-considerations
Size of the slots and FIFOs: 

$\frac{512k}{2*16}=16k$
$\frac{512k}{2*4}=64k$
%% Table analyse:
%%    Numrows: 5
%%    Most Long row size: 49
%%    Choose table mode: tabular
\begin{figure}[h]
\begin{tabular}{lll}
\hline
\multicolumn{1}{|l|}{ For 1 slot }&\multicolumn{1}{l|}{ Rx - ics554 }&\multicolumn{1}{l|}{ Tx - ics564 }\\ 
\hline
\multicolumn{1}{|l|}{ Samples }&\multicolumn{1}{l|}{ 2560*2=5120=5k }&\multicolumn{1}{l|}{ 2560*2=5120=5k }\\ 
\hline
\multicolumn{1}{|l|}{ Bytes }&\multicolumn{1}{l|}{ 5120*16=81920=80k }&\multicolumn{1}{l|}{ 5120*4=20480=20k }\\ 
\hline
\multicolumn{1}{|l|}{ FIFO-size [bytes] }&\multicolumn{1}{l|}{ 65536*8=512k }&\multicolumn{1}{l|}{ 65536*4*2=512k }\\ 
\hline
\multicolumn{1}{|l|}{ Max samples }&\multicolumn{1}{l|}{  }&\multicolumn{1}{r|}{   }\\ 
\hline
\end{tabular}
\end{figure}

The samples per slot is given by the pseudo-UMTS system of the software-radio and is fixed for the moment at 2560 samples. As we do an oversampling by a factor of 2, this gives 2560*2=5120 samples per slot, for both the ics554 and ics564.

The total bytes is calculated as $samples*bytes_ per_ samples$
, where $bytes_
per_ samples$
 is:


\begin{lyxlist}{00.00.0000}

\item [4]= 16bit real + 16bit imaginary


\item [16]= 32bit real + 32bit imaginary, but for two channels, as we can't treat only one channel at a time in the ics554-card

\end{lyxlist}

According to the ics-554 documentation E10681 Rev.B p. 55, the FIFO is sized at 65536 * 64bit-values, which gives 512kBytes. The ics-564 documentation E10734 Rev.- p. 9 gives the size 65536 16bit-samples as {}``approximately one quarter of the FIFO-size''. So the total is 65536*4*2 = 512kBytes.


\dokutitleleveltree{Conclusion}
\label{b669f32badeb976700cb6c9f7c7b5cdf}%% conclusion
 The DMA-size will be dependant on the slot-size. So, there will be 1 slot per DMA-transfer. This limits the slot-length to 16kSamples for the Rx-part, but that should be OK.

Care has to be taken for small slot-sizes, as the DMA-transfer happens in two steps: 


\begin{enumerate}\dokuitem  Fill up the FIFOs on the ics564
\dokuitem  Start the transfer
\dokuitem  Wait for underflow of the FIFOs and re-transmit
\end{enumerate}

\dokutitleleveltwo{Server}
\label{cf1e8c14e54505f60aa10ceb8d5d8ab3}%% server
 The old implementation of the server takes DMA{\textunderscore}BLOCK-sized packets and works on these. In order to rewrite only what is necessary, I adjusted the Base/Antenna/Simul{\textunderscore}ics in a way to chop down the slots into DMA{\textunderscore}BLOCK-sized packets. Too bad if it is not a multiple of these. There is no check against that.


\dokutitleleveltwo{Resampler}
\label{7a6604169119d50cce42afc39d75c015}%% resampler
 A big mess that nobody understands. Hopefully the work of the student this summer sheds some light on this.


\dokutitleleveltwo{Samples, Chips and Symbols}
\label{43650a466eb498dafba7ded7862ca694}%% samples_chips_and_symbols
 The current setup has 2 Samples for 1 Chip, and 1 Chip for 1 Symbol (without a spreading-sequence). This means, that there is a 2 x oversampling.

\part{HOWTOs}




\dokutitlelevelone{From Conception to Measurement}
\label{3239be1ec69baea6384eb34ea51a52e3}%% from_conception_to_measurement
\label{3239be1ec69baea6384eb34ea51a52e3}%%Start: from_conception_to_measurement => /var/www/html/ipgwww/data/pages/from_conception_to_measurement.txt
\label{cha:conception_to_measurement} \index{From Conception to Measurement|(} Of course the main idea behind the MSR is that you're able to write new modules for it. This chapter will give an introduction with an actual example of a module as well as an implementation of a radio-transmission. After this you should be able to create your own modules and put them into use. An important introduction can be found in chapter \ref{cha:simple radio}. You should also already have run the example in chapter \ref{cha:getting started}. This part is a bit heavy on coding, but you won't be able to write modules without a good knowledge of C.


\dokutitleleveltwo{Defining New Modules}
\label{9195931f3b80604f4a275a13664383be}%% defining_new_modules
\index{From Conception to Measurement!Defining new modules}

In here you will learn the most important things about a module, how it works, how to use it, and how to extend it. This example is already present in the tree, but you can read this section to get a feel of it.

The goal of this module will be to measure the SNR of the signal. Even though this functionality is already implemented in a module, it is a nice idea to have a possibility to compare the results of the two approaches. The existing module compares the received training sequence with the original in order to calculate the SNR. As the training sequence is only part of a transmitted slot, it is a good idea to compare this SNR with the SNR computed in here.

\begin{figure}
\begin{center}
 		\includegraphics{/var/www/html/ipgwww/data/media/graphviz/d35d2e3523872b2dea06bb74d70f9453.ps}
 \end{center}
\caption{\label{cap:The-example-slot}The example slot}
\end{figure}


In order to calculate the SNR differently, we will transmit a random sequence and then compare it after the transmission. This is depicted in fig. \ref{cap:The-example-slot}. In order to know the exact amplitude, it is important to know the random sequence in advance. This is done by setting the \dokuitalic{seed} parameter of the random-module.

Once we have the received signal $y=y_{r}+iy_{i}=[y_{0r}y_{1r}...y_{n-1r}]+i[y_{0i}y_{1i}...y_{n-1i}]$
 and the transmitted signal , we can calculate the amplitude:

$a=\frac{\sum_{l=0}^{n-1}y_{lr}sign(x_{lr})+y_{li}sign(x_{li})}{n}$


and also the variance:

$v=\frac{\sum_{l=0}^{n-1}(y_{lr}-a\, sign(x_{lr}))^{2}+(y_{li}-a\, sign(x_{li}))^{2}}{2n}$


and the signal to noise ratio is then

$SNR=10*\log(\frac{a^{2}}{v})$


The correctness of this assertion is left as an exercise to the reader.


\dokutitleleveltree{The Files}
\label{41c409177e6f2bede91d676ac7d11589}%% the_files
Now that we know what it is about, let's have a look at the written files. For your information you will learn where the templates for the files come from in every section. The discussion then is only about the parts that have been added. In the directory \dokuitalic{Modules/Signals}, there is a directory called \dokuitalic{SNR}. in there you find the code for the SNR-module. The MSR knows about this directory because of the file \dokuitalic{Modules/Signals/Makefile} that has an entry \dokuitalic{SNR} in the list of \dokuitalic{DIRS}. You can have a look at this Makefile to see it.

The template files come from the \dokuitalic{Conventions} directory and are called:


\small
\begin{verbatimtab}

Conventions/multi_*.c
Conventions/Makefile.module

\end{verbatimtab}
\normalsize
Most of the modules come in two parts: one sending part and one receiving part. But as they usually are used in a pair, they are put together into one module. So as not to be confused with different modules, they are renamed to:


\small
\begin{verbatimtab}

multi_template.c -> snr.c
multi_template_send.c -> snr_send.c
multi_template_rcv.c -> snr_rcv.c
Makefile.module -> Makefile

\end{verbatimtab}
\normalsize

\dokutitlelevelfour{snr.c}
Now look first at the file \dokuitalic{snr.c} and look at the places that contain some documentation. It is really important to keep this documentation up-to-date, so that other people know what it's about:


\small
\begin{verbatimtab}

SNR - measure the signal to noise ratio of a transmitted slot.
In order to do this, we send a slot of known random data that
is measured on the other side.

\end{verbatimtab}
\normalsize
This is all that is needed. Not a big description, just enough to know what it's about.

What it does is the following: once the module \dokuitalic{snr} is loaded into the memory, the function \dokuitalic{spc{\textunderscore}module{\textunderscore}init} is called, which in turn calls \dokuitalic{rcv{\textunderscore}module{\textunderscore}init} from \dokuitalic{snr{\textunderscore}rcv.c} and \dokuitalic{send{\textunderscore}module{\textunderscore}init} from \dokuitalic{snr{\textunderscore}send.c}. These two functions are responsible to tell the CDB about their name, their input and output as well as their paramters.


\dokutitlelevelfour{snr{\textunderscore}send.c}
This is the part that prepares the slot.

\dokubold{documentation. } At the top of the file, you see again a short description of the module


\small
\begin{verbatimtab}

snr_send.c - sends a slot of random symbols

\end{verbatimtab}
\normalsize
and a bit further down (after the copyright message) a bit more of description.


\small
\begin{verbatimtab}

This module expects some random input that is then modulated
using QPSK modulation so that the noise can be mesured. It can
send the QPSK symbols either on the axis or in the corners.

\end{verbatimtab}
\normalsize
\dokubold{config-structure} \index{Module!Example!config} We want the user to be able to change the amplitude of what we send over the channel. So, edit the config-structure, and make it something like:


\small
\begin{verbatimtab}

typedef struct {
  // The amplitude of the generated QPSK-signal
  int amplitude; // 32767
  // The QPSK-type, 0->in the corner, 1->on the axes
  int type; // 0
} config_t;

\end{verbatimtab}
\normalsize
It may seem strange that we take an integer for the amplitude, but you have to know that the signals are all in 16-bit integers, so what usually is between $+1$
 and $-1$
 is now between $+32767$
 and $-32768$
.

\dokubold{private-structure} \index{Module!Example!private} Once the user changed the configuration, we will store it in our private variable. This is more for convenience than anything else:


\small
\begin{verbatimtab}

typedef struct {
  int amplitude;
  int type;
} private_t;

\end{verbatimtab}
\normalsize
The other structure may be left empty, we don't need it for this example. Just after the structures is a function called

\dokubold{send{\textunderscore}init} \index{Module!Example!init} Why another initialisation function, you might ask. Well, remember from chapter \ref{sec:framework} that first the module is registered with the CDB, before it is possible to instantiate it. So, this function is what is called each time this module is instantiated. In our example, we just want to put a default-value in the amplitude-part of the configuration, so add this line:


\small
\begin{verbatimtab}

config->amplitude = 32767;
config->type = 0;

\end{verbatimtab}
\normalsize
32767 is the maximum number that we can have in a 16-bit signed variable.

\dokubold{send{\textunderscore}configure{\textunderscore}input} \index{Module!Example!configure_input} This function is called whenever the MSR wants to know what the size of the input should be, given the size of the output. So, for each 2 bit of input, we create one symbol with the QPSK representation. This means that two bits of input create one symbol of output, at least for an even number of symbol-outputs. The only tricky part here is that the input is not counted in bits, but rather in bytes. So $size_{input}=\frac{2*size_{output}}{8}$
, which is written in this function as


\small
\begin{verbatimtab}

size_in(0) = ( size_out(0) + 7 ) * 2 / 8;

\end{verbatimtab}
\normalsize
This assures that we always have enough bits to write to the output.

\dokubold{send{\textunderscore}configure{\textunderscore}output} \index{Module!Example!configure_output} The same as before, but this time the opposite direction:


\small
\begin{verbatimtab}

size_out(0) = size_in(0) * 8 / 2;

\end{verbatimtab}
\normalsize
\dokubold{send{\textunderscore}reconfig} \index{Module!Example!reconfig} We use this function to copy the configuration-data to our private structure:


\small
\begin{verbatimtab}

private->amplitude = config->amplitude;
private->type = config->type;

\end{verbatimtab}
\normalsize
\dokubold{send{\textunderscore}pdata} \index{Module!Example!send_pdata} Now comes finally the processing function. This is where the main action takes place. Let's first define some variables:


\small
\begin{verbatimtab}

// Definition of variables - don't touch
stats_t *stats;
int i, amp;
U8 *in;
SYMBOL_COMPLEX *out;

\end{verbatimtab}
\normalsize
To get to the input and output-buffers, we have to do the following:


\small
\begin{verbatimtab}

in = buffer_in(0);
out = buffer_out(0);

\end{verbatimtab}
\normalsize
The first line deletes the \dokuitalic{data} bit on the input-port, signaling the MSR that the input-port is free again to receive some data. Furthermore it returns a pointer to the input-buffer of this module. The second line gets the output-buffer of this module and sets the \dokuitalic{data} bit on the output-port. Once this function returns, the MSR checks for the \dokuitalic{data}-bit in the output-port and, if it is set, handles the processing to the next module.

OK, now we just have to process the data:


\small
\begin{verbatimtab}

// Fill the slot with random QPSK symbols
for ( i=0; i<size_out(0); i++ ){
  switch( 2 ){
  case 1:
    // The amplitude in this case is
    // Sqrt( Re^2 + Im^2 ) and thus the
    // desired amplitude has to be divided by
    // sqrt(2)
    amp = private->amplitude / sqrt( 2 );
    out[i].real = ( 2 * ( *in & 1 ) - 1 ) * amp;
    *in = *in >> 1;
    out[i].imag = ( 2 * ( *in & 1 ) - 1 ) * amp;
    *in = *in >> 1;
    break;
  case 2:
    amp = private->amplitude;
    if ( *in & 1 ){
      *in = *in >> 1;
      out[i].real = ( 2 * ( *in & 1 ) - 1 ) * amp;
      out[i].imag = 0;
    } else {
      *in = *in >> 1;
      out[i].imag = ( 2 * ( *in & 1 ) - 1 ) * amp;
      out[i].real = 0;
    }
    *in = *in >> 1;
    break;
  }
  // Get the next input-byte of random
  if ( i && !( i % 4 ) ){
    in++;
  }
}

\end{verbatimtab}
\normalsize
You might not be completely fond of this example, but it works (yet to check).

\dokubold{send{\textunderscore}custom{\textunderscore}message} This function is not needed and can be deleted

\dokubold{send{\textunderscore}module{\textunderscore}init} \index{Module!Example!module_init} Registers this module with the CDB. The CDB first wants to be informed about the type of module to be attached \dokufootnote{For further information, look at \ref{subsec:cdb}
}. In our case, we have one input, one output, one config-parameter and 0 stats-parameter:


\small
\begin{verbatimtab}

desc = swr_spc_get_new_desc( 1, 1, 2, 0 );

\end{verbatimtab}
\normalsize
Then we have to tell about the config-parameter, the input-type and the output-type:


\small
\begin{verbatimtab}

UM_CONFIG_INT( ''amplitude'' );
UM_CONFIG_INT( ''type'' );
UM_INPUT( SIG_U8, 0 );
UM_OUTPUT( SIG_SYMBOL_COMPLEX, 0 );

\end{verbatimtab}
\normalsize
In order for the MSR to know what functions to call in what case, we have to define 'call-back functions'. As these are always the same, they are already pre-defined in the templates, and we only have to delete the \dokuitalic{send{\textunderscore}custom{\textunderscore}msg} entry. Now the module-description is complete, save for the name:


\small
\begin{verbatimtab}

send_id = swr_cdb_register_spc( &desc, "snr_send" );

\end{verbatimtab}
\normalsize

\dokutitlelevelfour{snr{\textunderscore}rcv.c}
Let's start with the comment in the beginning of the file:


\small
\begin{verbatimtab}

This module receives the stream from the matched filter
and the stream of random-signals that are supposed to be
the same that have been used by the snr_send. It then
calculates the amplitude, the variance and the snr.

\end{verbatimtab}
\normalsize
This means that this module has two inputs: one from the channel, and another one from the random-module.

\dokubold{config-structure} \index{Module!Example!config} Again we have the possibility to change the type:


\small
\begin{verbatimtab}

typedef struct {
  // The QPSK-type, 0->in the corner, 1->on the axes
  int type;
} config_t;

\end{verbatimtab}
\normalsize
\dokubold{stats-structure} \index{Module!Example!stats} So we're able to retrieve the SNR from the outside, we have to write it in this structure:


\small
\begin{verbatimtab}

typedef struct {
  double snr;
} stats_t;

\end{verbatimtab}
\normalsize
\dokubold{rcv{\textunderscore}init} \index{Module!Example!init} Let's just start with a SNR of -2.3:


\small
\begin{verbatimtab}

stats->snr = -2.3;
config->type = 0;

\end{verbatimtab}
\normalsize
\dokubold{rcv{\textunderscore}reconfigure} \index{Module!Example!reconfigure}


\small
\begin{verbatimtab}

private->type = config->type;

\end{verbatimtab}
\normalsize
The functions \dokuitalic{rcv{\textunderscore}configure{\textunderscore}input} and \dokuitalic{rcv{\textunderscore}configure{\textunderscore}output} can be deleted, as this module is at the end of the chain.

\dokubold{rcv{\textunderscore}pdata} \index{Module!Example!pdata} Here goes the working function. It's just about implementing the above formula. Let's go through step by step. Definition of variables:


\small
\begin{verbatimtab}

stats_t *stats;
SYMBOL_COMPLEX *in, *buf_rnd;
U8 *in_rnd;
double signal = 0., noise = 0.;
int i;

\end{verbatimtab}
\normalsize
Then we have to make sure that we have both the signal from the channel and the random-data:


\small
\begin{verbatimtab}

if ( !data_available(0)    !data_available(1) ){
  PR_DBG( 4, "Not all data available yet\n" );
  return 0;
}

\end{verbatimtab}
\normalsize
Now we reconstruct  so that we can implement the formula given above. Instead of calculating  and then taking the sign of it, we directly calculate  with an amplitude of $\pm1$
. Again, once for the QPSK-signals on the axes, and once for the signals tilted by $\frac{\pi}{4}$



\small
\begin{verbatimtab}

in_rnd = buffer_in(1);
buf_rnd = swr_malloc( size_in(0) * sizeof( SYMBOL_COMPLEX ) );
for ( i=0; i<size_in(0); i++ ){
  switch( private->type ){
  case 0:
    buf_rnd[i].real = ( 2 * ( *in_rnd & 1 ) - 1 );
    *in_rnd = *in_rnd >> 1;
    buf_rnd[i].imag = ( 2 * ( *in_rnd & 1 ) - 1 );
    *in_rnd = *in_rnd >> 1;
    break;
  case 1:
    if ( *in_rnd & 1 ){
      *in_rnd = *in_rnd >> 1;
      buf_rnd[i].real = ( 2 * ( *in_rnd & 1 ) - 1 );
      buf_rnd[i].imag = 0;
    } else {
      *in_rnd = *in_rnd >> 1;
      buf_rnd[i].imag = ( 2 * ( *in_rnd & 1 ) - 1 );
      buf_rnd[i].real = 0;
    }
    *in_rnd = *in_rnd >> 1;
    break;
  }
  // Get the next input-byte of random
  if ( i && !( i % 4 ) ){
    in_rnd++;
  }
}

\end{verbatimtab}
\normalsize
Now we can calculate the amplitude of the signal:


\small
\begin{verbatimtab}

in = buffer_in(0);
// Calculate signal energy
for ( i=0; i<size_in(0); i++ ){
  signal += (double)( in[i].real ) * buf_rnd[i].real +
    (double)( in[i].imag ) * buf_rnd[i].imag;
}
signal = signal / size_in(0);

\end{verbatimtab}
\normalsize
And the noise-variance:


\small
\begin{verbatimtab}

for ( i=0; i<size_in(0); i++ ){
  noise += pow( (double)in[i].real - signal * buf_rnd[i].real, 2 ) +
    pow( (double)in[i].imag - signal * buf_rnd[i].imag, 2 );
}
noise = noise / size_in(0) / 2;

\end{verbatimtab}
\normalsize
Finally we can calculate the snr:


\small
\begin{verbatimtab}

PR_DBG( 2, "signal_amp: %i, noise_amp: %g\n",
        (int)signal, noise );
// And write the snr
swr_sdb_get_stats_struct( context->id, (void**)&stats );
if ( noise > 0 ){
  stats->snr = 10 * ( log10( signal ) * 2 - log10( noise ) );
}
swr_free( buf_rnd );

\end{verbatimtab}
\normalsize
Again, the \dokuitalic{rcv{\textunderscore}user{\textunderscore}msg} is not used and can be deleted. \dokubold{rcv{\textunderscore}module{\textunderscore}init} We have only 1 input, no output, 1 config-variable and 1 stats-variable, and lots of functions are not used:


\small
\begin{verbatimtab}

desc = swr_spc_get_new_desc( 1, 0, 1, 1 );
UM_STATS_DOUBLE( ''snr'' );
UM_INPUT( SIG_SYMBOL_COMPLEX, 0 );
desc->fn_init              = rcv_init;
desc->fn_reconfigure       = rcv_reconfig;
desc->fn_process_data      = rcv_pdata;
desc->fn_finalize          = rcv_finalize;
rcv_id = swr_cdb_register_spc( &desc, "snr_rcv" );

\end{verbatimtab}
\normalsize

\dokutitlelevelfour{Makefile}
\index{Module!Example!Makefile} In the makefile we have to tell the final name of the module, as well that we use the math-library:


\small
\begin{verbatimtab}

MODULE_NAME = snr
MATH = true

\end{verbatimtab}
\normalsize

\dokutitleleveltree{Compile it}
\label{e6ee3984de104e04f06a961f6a7b263a}%% compile_it
Now you can try to compile it by typing \dokuitalic{make} on the command-line. If there are any errors, try to fix them, the above lines should work, they have been tested. In order to include this module even better in the MSR, you can add the name of the directory to the file \dokuitalic{Modules/Signals/Makefile} in the line \dokuitalic{DIRS} = . Like this a top-level \dokuitalic{make} will also update the SNR-module.


\dokutitleleveltwo{Testing}
\label{ae2b1fca515949e5d54fb22b8ed95575}%% testing
Up to now only the module has been written. It is not yet in a usable state, as it is only registered with the CDB, but not yet instantiated. Theoretically we could write everything in the module to make an instance, but this would turn upside-down the idea of modules. So what we need is an own program that implements the chain and runs it, just to look how good it runs.

Perhaps as a surprise, this program will again be a module, but this time a module that does actually something. Implementing a simple chain. So there is a function called \dokuitalic{um{\textunderscore}module{\textunderscore}init} that will be called upon inserting the module. This function itself creates a new thread that will be used to create the chain. In order to be compatible for further RTLinux implementation, we have to do this two-step calling.


\dokutitleleveltree{The Directory}
\label{09155c01744551c42bb769358e4f1c13}%% the_directory
In the MSR, there is a directory called \dokuitalic{Test} which holds already different tests. The test for the SNR is of course in a directory called \dokuitalic{Test/SNR}. The templates for the test-module are in


\small
\begin{verbatimtab}

Conventions/test_template.c
Conventions/Makefile.module

\end{verbatimtab}
\normalsize
Again, for easier handling they are renamed:


\small
\begin{verbatimtab}

test_template.c -> test_snr.c
Makefile.module -> Makefile

\end{verbatimtab}
\normalsize

\dokutitleleveltree{Makefile}
\label{cd5dbf3629c558b0104ba8f0937d6816}%% makefile
The makefile wants to know the name of the module, which is \dokuitalic{test{\textunderscore}snr}, as well as the modules to load in order for the MSR to function correctly. In our case, these are the modules \dokuitalic{random, snr, midamble, rrc} and \dokuitalic{block}:


\small
\begin{verbatimtab}

MODULE_NAME = test_snr
DEPENDS = random snr chest rrc block

\end{verbatimtab}
\normalsize

\dokutitleleveltree{test{\textunderscore}snr.c}
\label{3f8b9add0bee393c6b26a1acdac9c7ed}%% test_snr.c
Let's have a look at the documentation:


\small
\begin{verbatimtab}

Make a simple chain:
random - snr_send - chest_send - rrc - block -
         rrc_rcv - chest_rcv - snr_rcv
and additionally:
random - snr_rcv(2)

\end{verbatimtab}
\normalsize
Then we can create our main-function, which is called \dokuitalic{start{\textunderscore}it} for the test-program.


\dokutitlelevelfour{start{\textunderscore}it}
The first thing we have to do is to create a \dokuitalic{chain} of modules. A chain is a logical suit of signal-processing modules, that take some input and produce some output that is handled further down the chain.

When using the \dokuitalic{swr{\textunderscore}chain{\textunderscore}create} functionwe give a list of all modules, that will be automatically connected together, and finish the list with END{\textunderscore}CHAIN. In this call to \dokuitalic{swr{\textunderscore}chain{\textunderscore}create}, you see three different kind of macros, \dokuitalic{NEW{\textunderscore}SPC{\textunderscore}VAR}, \dokuitalic{NEW{\textunderscore}SPC} and OLD{\textunderscore}SPC{\textunderscore}IN all of which are described in \ref{subsec:sdb}. In short, while the former allows you to give a variable where a reference to the module will be stored, the latter just creates the module and connects it, without giving the reference of the created module. The third takes an already defined module for further connections.


\small
\begin{verbatimtab}

swr_sdb_id rnd, mafi, snr_rcv;
test_chain = swr_chain_create(
                      NEW_SPC_VAR( ''random'', rnd ),
                      NEW_SPC_VAR( ''snr_send'' ),
                      NEW_SPC( ''chest_send'' ),
                      NEW_SPC( ''rrc'' ),
                      NEW_SPC_VAR( ''block'' ),
                      NEW_SPC_VAR( ''rrc_rcv'', mafi ),
                      NEW_SPC_VAR( ''chest_rcv'', mafi ),
                      NEW_SPC_VAR( ''snr_rcv'', snr_rcv ),
                      END_CHAIN );
swr_sdb_set_config_int( mafi, "cacl_taps", 8 );
test_chain_2 = swr_chain_create(
                      NEW_SPC_VAR( ''random'', rnd2 ),
                      OLD_SPC_IN( snr_rcv, 1 ),
                      END_CHAIN );

\end{verbatimtab}
\normalsize
So we have created a chain. The modules have the following function: 
\begin{lyxlist}{00.00.0000}

\item [random]create random bytes


\item [snr{\textunderscore}send]our module created above, takes some random bytes as input, and creates a QPSK output


\item [chest{\textunderscore}send]inserts the training-sequence in the middle of the stream


\item [rrc] Root Raised Cosine pulse-shape filtering


\item [block]a very simple channel-simulation


\item [rrc{\textunderscore}rcv] Applies again the Root Raised Cosine filtering


\item [chest{\textunderscore}rcv]uses the training-sequence to make a channel-estimation and does a matched-filtering on the received samples


\item [snr{\textunderscore}rcv]our module to calculate the SNR

\end{lyxlist}

If we compile and test our module with \dokuitalic{make; make user}, this chain will be created and the program will exit. What we forgot is to really use this chain. For this, the \dokuitalic{random} module listens to user-messages, and begins creating a random-output whenever it receives such a user-message. But first we have to make sure that both random-modules create the same values:


\small
\begin{verbatimtab}

swr_sdb_set_config_int( rnd, "seed", 0x1234 );
swr_sdb_set_config_int( rnd2, "seed", 0x1234 );

\end{verbatimtab}
\normalsize
Then we adjust a bit the amplitudes, so that we don't run all the time on the edge:


\small
\begin{verbatimtab}

swr_sdb_set_config_int( snr_send, "amplitude", 16384 / 4 );
swr_sdb_set_config_int( mid, "amplitude", 16384 / 4 );

\end{verbatimtab}
\normalsize
To make it a bit more nice, we have a look at different values, using the \dokuitalic{sigma} parameter of the \dokuitalic{block} module:


\small
\begin{verbatimtab}

for ( i=0; i<50; i+=5 ){
  swr_sdb_set_config_double( block, "sigma", i );
  swr_sdb_send_msg( rnd, SUBS_MSG_USER, NULL, -1 );
  swr_sdb_send_msg( rnd2, SUBS_MSG_USER, NULL, -1 );
  PR( "Amp: %2i:%2i, Noise: %3i:%3i  SNR : %5.5g - %5.5g = %5.5g\n",
      swr_sdb_get_stats_int( mafi, "mid_amp" ),
      swr_sdb_get_stats_int( snr_rcv, "amp" ),
      swr_sdb_get_stats_int( mafi, "noise_var" ),
      swr_sdb_get_stats_int( snr_rcv, "var" ),
      swr_sdb_get_stats_double( mafi, "snr" ),
      swr_sdb_get_stats_double( snr_rcv, "snr" ),
      swr_sdb_get_stats_double( mafi, "snr" ) -
      swr_sdb_get_stats_double( snr_rcv, "snr" ) );
}

\end{verbatimtab}
\normalsize
And after a \dokuitalic{make; make user} you should see something like:


\small
\begin{verbatimtab}

Amp: 63:63, Noise:   1:1   SNR : 34.40 - 34.24 =  0.15426
Amp: 62:62, Noise:   5:6   SNR : 28.52 - 28.10 =  0.42007
Amp: 62:62, Noise:  27:26  SNR : 21.50 - 21.58 = -0.077267
Amp: 62:62, Noise:  66:63  SNR : 17.61 - 17.83 = -0.21601
Amp: 62:61, Noise: 122:111 SNR : 14.96 - 15.34 = -0.37944
Amp: 61:61, Noise: 190:187 SNR : 12.89 - 13.07 = -0.18071
Amp: 58:59, Noise: 179:219 SNR : 12.72 - 12.01 =  0.70692
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{verbatimtab}
\normalsize
So you see that our method gives more or less the same results as the \dokuitalic{snr} calculated in the \dokuitalic{matched{\textunderscore}filter}.


\dokutitleleveltwo{Going Over the Air}
\label{ae9146d472e44cd4310c0190fb7b5734}%% going_over_the_air
OK, now that the module is written, a simple test-case shows that our module works, 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.


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


\small
\begin{verbatimtab}

simple_radio.h
Makefile
BS/Makefile
BS/radio_bs.c
MS/Makefile
MS/radio_ms.c

\end{verbatimtab}
\normalsize
To reflect the fact that it isn't the \dokuitalic{simple} radio anymore, we have to adjust the names in the Makefiles. The first lines in \dokuitalic{BS/Makefile} contains:


\small
\begin{verbatimtab}

MODULE_NAME = radio_snr_bs
DEPENDS = rrc synch energy mapper chest random \
          rndstr spread sink cch macro_sch snr

\end{verbatimtab}
\normalsize
and in \dokuitalic{MS\dokufootnote{Microsoft}/Makefile} reads:


\small
\begin{verbatimtab}

MODULE_NAME = radio_snr_ms
DEPENDS = rrc synch energy mapper chest random \
          rndstr spread sink macro_synch macro_sch snr

\end{verbatimtab}
\normalsize

\dokutitleleveltree{README}
\label{3905d7917f2b3429490b01cfb60d8f5b}%% readme
This file also reflects the changes and has a very small documentation in it.


\dokutitleleveltree{MS/radio{\textunderscore}ms.c}
\label{4b5339093cf60b4c42ae7c412edd2dd7}%% ms_radio_ms.c
There is a lot of things to say about the basic system. You can find an introduction in \ref{cha:simple radio}. 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 \dokuitalic{synchronised}. Near the end of this function, you have to replace the declaration of the UP-chain with the following chain:


\small
\begin{verbatimtab}

// And setup a simple UP-chain...
ch_up = swr_chain_create(
                      NEW_SPC_VAR( "random", rnd ),
                      NEW_SPC( "snr_send" ),
                      NEW_SPC( "chest_send" ),
                      NEW_SPC( "rrc" ),
                      OLD_SPC_IN( stfa, 1 ),
                      CHAIN_END );
swr_stfa_notice_sdb( stfa, 1, rnd );
PR( "Ready to go" );

\end{verbatimtab}
\normalsize
You see a new macro in the function \dokuitalic{swr{\textunderscore}chain{\textunderscore}create} here, which is called \dokuitalic{OLD{\textunderscore}SPC{\textunderscore}IN} and uses the \dokuitalic{stfa} module. The macro tells the function that this module has already been created before. The module \dokuitalic{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 \dokuitalic{random} module every frame to the same value. Like this we're sure that both the BS and the MS\dokufootmark{2} have the same random-values. To achieve this, the function \dokuitalic{do{\textunderscore}send{\textunderscore}up} is handy. It is called once in a frame, and we can put the following line in there:


\small
\begin{verbatimtab}

swr_sdb_set_config_int( rnd, "seed", 0x1234 );

\end{verbatimtab}
\normalsize
That's it for the mobile-station part.


\dokutitleleveltree{radio{\textunderscore}bs.c}
\label{337e328eef3c2a2c538baeffc2bd4930}%% 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 \dokuitalic{radio{\textunderscore}ms.c}. So we can directly change the construction of the UP-chain in the function \dokuitalic{start{\textunderscore}it} to:


\small
\begin{verbatimtab}

PR( "Setting uplink in slot 1\n" );
ch_rach = swr_chain_create(
                 OLD_SPC_OUT( stfa, 1 ),
                 NEW_SPC( "rrc_rcv" ),
                 NEW_SPC_VAR( "chest_rcv", mafi ),
                 NEW_SPC( "snr_rcv" ),
                 CHAIN_END );
ch_rach_2 = swr_chain_create( NEW_SPC_VAR( "random", rnd ),
                              OLD_SPC_IN( snr_rcv, 1 ),
                              CHAIN_END );
swr_sdb_set_config_int( sch, "mafi0", mafi );
while ( looping++ ){
  usleep( 1000000 );
  PR( "mafi0: %g, mafi1: %g\n",
      swr_sdb_get_stats_double( mafi, "snr" ),
      swr_sdb_get_stats_double( snr_rcv, "snr" ) );
}

\end{verbatimtab}
\normalsize
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 \dokuitalic{do{\textunderscore}send{\textunderscore}down}, which is used once a slot. So we can insert there:


\small
\begin{verbatimtab}

swr_sdb_set_config_int( rnd, "seed", 0x1234 );
swr_sdb_send_msg( rnd, SUBS_MSG_USER, NULL, -1 );

\end{verbatimtab}
\normalsize

\dokutitleleveltree{Running it with the channel-simulation}
\label{8f735787bb2de38c33c153334ef89984}%% 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 \dokuitalic{Radios/SNR} and type \dokuitalic{make} to compile it, and \dokuitalic{make server; make show{\textunderscore}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 \dokuitalic{make} again. If something goes wrong with the display, type \dokuitalic{make kill; make cleanproc} which should clean-up the directories, and then you can try \dokuitalic{make server;
make show{\textunderscore}bsms} again.


\dokutitleleveltree{Running the real thing}
\label{fbc58a23e218ca05b8d408a3e51902be}%% 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 \dokuitalic{make rf{\textunderscore}show} from the \dokuitalic{Radios/SNR/BS} directory. Then, on the other machine, you can run \dokuitalic{make rf{\textunderscore}show} from the \dokuitalic{Radios/SNR/MS\dokufootmark{2}} 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|)}

 


\dokutitlelevelone{Tools}
\label{4a931512ce65bdc9ca6808adf92d8783}%% tools
\label{4a931512ce65bdc9ca6808adf92d8783}%%Start: tools => /var/www/html/ipgwww/data/pages/tools.txt
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.


\dokutitleleveltwo{Visualize}
\label{f279a48f784b90100d413ca55dfc9bfd}%% visualize
\label{sub:Visualize} \index{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 \dokuitalic{Test}-directory), Visualize can't show the complete chain.


\dokutitleleveltree{Starting it}
\label{cacc89d7318964383f5c2adf67e9714d}%% starting_it
To run it, simply type \dokuitalic{make show} and enter. This sets up the path so that the \dokuitalic{qwt} library can be found. The executable first searches for a real-time MSR that puts its data into \dokuitalic{/proc/sradio}, then it searches for the most recent entry in \dokuitalic{/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 \dokuitalic{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.


\dokutitleleveltree{Mouse handling}
\label{55eb03beb53aa95455fb8b8ee0d6a3bc}%% 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.


\dokutitleleveltree{Plotting of values}
\label{230c998ccc23666d1f28520ebdc04747}%% plotting_of_values
\label{visualize_plotting} There is a possiblity to plot the \dokuitalic{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 \dokuitalic{File} menu and chose \dokuitalic{Stats Plot XY} or \dokuitalic{Stats Plot Y(t)}. Now you can click on a module in order to get a list of \dokuitalic{stats} that shall be plotted. If you chose \dokuitalic{Stats
Plot XY}, you have to chose a second module and a second \dokuitalic{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 \dokuitalic{visualize} tool, only the 1000 most recent samples are shown. This assures that you can have 1 million or more samples, and still have \dokuitalic{visualize} react to your requests. If you chose to \dokuitalic{export to matlab}, all samples will be exported. If you chose \dokuitalic{export to ps}, only the visible samples will be plotted.


\dokutitleleveltree{Exporting values}
\label{5132db779b1f6332fef09cbcbc4b78c1}%% exporting_values
\label{visualize_exporting} 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 button.


\dokutitleleveltree{Known bugs}
\label{2d7d1ad71b4d928a9b2689402e095f66}%% 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.


\dokutitleleveltwo{Channel-server}
\label{5f8af2d3e680b2739b917e00c944e5f7}%% channel-server
\label{sub:Channel-server} \index{Channel-server} The channel-server takes the inputs of different radios, mixes them together and sends them back to the different radios. 


\dokutitleleveltree{Starting it}
\label{cacc89d7318964383f5c2adf67e9714d}%% starting_it
When you're in the \dokuitalic{Main}/ structure somewhere, usually it is enough to type \dokuitalic{make server} to start the channel-server. This is only necessary once. 


\dokutitleleveltree{Known bugs}
\label{2d7d1ad71b4d928a9b2689402e095f66}%% 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 \dokuitalic{killall
server} followed by a \dokuitalic{make server}.


\dokutitleleveltwo{LDPC-code generation}
\label{6e15231582941912cfc7215a580a31d2}%% ldpc-code_generation
\label{sub:LDPC-code-generation} \index{LDPC-code generator} In \dokuitalic{Tools/LDPC} you find a program that takes descriptions of LDPC-codes and puts them in a module-readable way.


\dokutitleleveltree{Starting it}
\label{cacc89d7318964383f5c2adf67e9714d}%% 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 \dokuitalic{write
code1 code2} for putting \dokuitalic{code1} and \dokuitalic{code2} into a file called \dokuitalic{graphs.c} which has to be copied into \dokuitalic{Modules/Coding/LDPC}. After a recompilation you're ready to use the new codes.


\dokutitleleveltree{Known bugs}
\label{2d7d1ad71b4d928a9b2689402e095f66}%% known_bugs
The length of the code is fixed for the moment at 4000 bits.

 


\dokutitlelevelone{Debugging}
\label{59f2da35bcc39525b87932b4cc1f3d68}%% debugging
\label{59f2da35bcc39525b87932b4cc1f3d68}%%Start: debugging => /var/www/html/ipgwww/data/pages/debugging.txt
\index{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.


\dokutitleleveltwo{Debugging in user-space}
\label{95ef33c1e7a3887707648a65cb7108a5}%% debugging_in_user-space
When the software-radio runs in real-time, it is very difficult to debug the radio. This is due to the fact that no delay is permitted in either radio, or else synchronisation will be lost. On the other hand, in user-space, we don't have this issue. If one radio is stopped, all other radios will be stopped, too, and synchronisation will NOT be lost. For this reason, debugging in user-space is usually the only way to debug a misbehaving module.

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.


\dokutitleleveltree{Using Gdb with Tests}
\label{2128eecbf867533d9e09d62057841fd6}%% using_gdb_with_tests
\index{Debugging!Tests} The first thing to do when a module doesn't run and stops with a \dokuitalic{segmentation
fault} is to use \dokuitalic{make debug} instead of \dokuitalic{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 \dokuitalic{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 \dokuitalic{list sdb.c:234}

\end{lyxlist}


\dokutitleleveltree{Debugging a Simulation}
\label{a3d5a1cb68bf19cceb6939afbaced02b}%% debugging_a_simulation
\index{Debugging!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\dokufootnote{Microsoft} in another window.

 Sometimes the two radios behave nicely, but it is only after changing some configuration-value with the visualize-tool that the system crashes. For this reason we start a visualize-tool in a third window, after the BS and MS\dokufootmark{1} are started. shell1, shell2 and shell3 denote three different windows or shells.


\small
\begin{verbatimtab}

shell1:SRadio/Radios/Simple/BS$ make server debug
shell2:SRadio/Radios/Simple/MS$ make debug
shell3:SRadio/Radios/Simple$ make show

\end{verbatimtab}
\normalsize
This starts the server and the BS, then starts the MS\dokufootmark{1}. 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.


\dokutitleleveltree{Using ddd}
\label{b2c0bf381cbefd11e0a89c09ac0e389b}%% using_ddd
\index{Debugging!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 \dokuitalic{ddd}. To start it, you go to the same directory where usually you type \dokuitalic{make
user} and type \dokuitalic{make ddd}. After this, you have to type \dokuitalic{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 \dokuitalic{Makefile}).

Now you can enter the name of a function to debug on top in the white box and press on \dokuitalic{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 \dokuitalic{cont} and watch what happens. \dokuitalic{next}, \dokuitalic{step}, right-clicking on variables are other nice options to take. Try it, break it. Debugging is an art!


\dokutitlelevelfour{Known bugs}
DO NOT type \dokuitalic{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 \dokuitalic{Program-{\textbackslash}textgreater{}Run Again}. Optionally you can use the F3-key.

 


\dokutitlelevelone{Getting Started}
\label{46b862bd16703034ef594b2996ec8166}%% getting_started
\label{46b862bd16703034ef594b2996ec8166}%%Start: getting_started => /var/www/html/ipgwww/data/pages/getting_started.txt
\label{cha: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.


\dokutitleleveltwo{Prerequisites}
\label{b5b8e67d6a37d24ad73c89e4c7ac8c9e}%% 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.1/sarge. The most common missing programs are: 
\begin{lyxlist}{00.00.0000}

\item [linker]check with \dokuitalic{ld version} whether it is something newer or equal than 12.13.90


\item [qt]check with \dokuitalic{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.


\dokutitleleveltwo{Installing the MSR}
\label{2d3a12d5dc1f8f93e98872c414f120e7}%% 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. 


\dokutitleleveltree{Download the software}
\label{35fe3a2f0bae73758455b7587a7e8043}%% download_the_software
From \href{http://lcmpc10.epfl.ch/Menu/Download}{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 \dokuitalic{tar xzf msr-*tgz} This will create a directory named \dokuitalic{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. 


\dokutitleleveltree{Compile the software}
\label{6bc2220730f8e238498103011d9403ba}%% 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 \dokuitalic{Main/Tools/Visualize} and run \dokuitalic{qmake visualize.pro} followed by a \dokuitalic{make}. If everything goes well, you should have an executable called visualize. After this you can change in the \dokuitalic{Main} directory and run \dokuitalic{make} there. Supposing that everything goes well, you're ready to run the examples. 


\dokutitleleveltree{Common errors}
\label{f663f14280bb137cd606a3387cf8e255}%% common_errors

\dokutitlelevelfour{While compiling 'Visualize' I get 'libqwt not found'}
Make sure that libqwt is installed and check eventually the path in visualize.pro.


\dokutitleleveltwo{Running the examples}
\label{a55e88c6683cb30cb26a8fba27542622}%% running_the_examples
There are a couple of pre-defined radios in the subdirectory \dokuitalic{Radios}/. The most simple is in \dokuitalic{Radios/Simple}/. Using the following commands, you can display both the BS and the MS\dokufootnote{Microsoft} of this simple example:


\small
\begin{verbatimtab}

cd Radios/Simple
make server
make show_bsms

\end{verbatimtab}
\normalsize
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 \dokuitalic{Multiuser} and \dokuitalic{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!

 


\dokutitlelevelone{Testing}
\label{ae2b1fca515949e5d54fb22b8ed95575}%% testing
\label{ae2b1fca515949e5d54fb22b8ed95575}%%Start: testing => /var/www/html/ipgwww/data/pages/testing.txt
\index{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.


\dokutitleleveltwo{Files}
\label{45b963397aa40d4a0063e0d85e4fe7a1}%% files
\label{sub:Files} \index{Testing!Files} If you want to start a new test, create a new directory under \dokuitalic{Test}/ and add the name to the line 


\small
\begin{verbatimtab}

DIRS = FirstChain Memory ...

\end{verbatimtab}
\normalsize
 of the file \dokuitalic{Test/Makefile}. Like this your test will be automatically built when using \dokuitalic{make whole}. Next \dokuitalic{cd} in your new directory and copy some files: 


\small
\begin{verbatimtab}

cp ../../Conventions/test_template.c ../../Conventions/Makefile.module .

\end{verbatimtab}
\normalsize
 The \dokuitalic{test{\textunderscore}template.c} should be renamed to something fitting the pattern \dokuitalic{test{\textunderscore}*.c}, and this name should be appended to the line 


\small
\begin{verbatimtab}

MODULE_NAME ==

\end{verbatimtab}
\normalsize
 of the \dokuitalic{Makefile} (which has been renamed from \dokuitalic{Makefile.module}). Now you are ready to modify your \dokuitalic{test{\textunderscore}*.c} file and test it out, using 


\small
\begin{verbatimtab}

make
make user

\end{verbatimtab}
\normalsize
 You can also have a look into different files that you find in the directory \dokuitalic{Testing/*} to see different techniques on how to do strange things.


\dokutitleleveltwo{Main}
\label{fad58de7366495db4650cfefac2fcd61}%% main
\label{sub:Main} \index{Testing!Main} The main-part of the module is in the function \dokuitalic{start{\textunderscore}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


\small
\begin{verbatimtab}

swr_chain_create( NEW_SPC_VAR( ''random'', rnd ),
                  NEW_SPC( ''modulator'' ),
                  NEW_SPC( ''demodulator'' ),
                  NEW_SPC_VAR( ''sink'', sink ),
                  CHAIN_END );

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


\small
\begin{verbatimtab}

swr_sdb_set_config_int( sink, ''size'', 128 );

\end{verbatimtab}
\normalsize
And while we're at it, we can tell the \dokuitalic{sink} module, that it should count the occurences of the different values:


\small
\begin{verbatimtab}

swr_sdb_set_config_int( sink, ''flag'', 2 );

\end{verbatimtab}
\normalsize
For further explanation, you can turn to the explanation of the \dokuitalic{sink} module.

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


\small
\begin{verbatimtab}

swr_sdb_seng_msg( rnd, SUBS_MSG_USER, NULL, -1 );

\end{verbatimtab}
\normalsize
Which sends a user-defined message to the \dokuitalic{random} module. It will now traverse the whole chain and the \dokuitalic{sink} module will output the occurances of the different values. To compile and start it, type the following commands:


\small
\begin{verbatimtab}

make
make user

\end{verbatimtab}
\normalsize
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.

 


\dokutitlelevelone{Using CVS}
\label{89d6d3bf5e82fdf45cf1b1c957d612b4}%% using_cvs
\label{89d6d3bf5e82fdf45cf1b1c957d612b4}%%Start: using_cvs => /var/www/html/ipgwww/data/pages/using_cvs.txt
\index{CVS} In this chapter you'll get an overview of the CVS\dokufootnote{Concurrent Versions System}-structure we're using for our software-radio. It is assumed that you already worked sometimes with CVS\dokufootmark{1} and that you know about the basic ideas and advantages of CVS\dokufootmark{1}.

CVS\dokufootmark{1} 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\dokufootmark{1} with this structure.


\dokutitleleveltwo{Structure}
\label{07414f4e15ca943e6cde032dec85d92f}%% structure
Usually one has a structure with one primary \dokuitalic{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 \dokuitalic{root}. This made it impossible to have a shared directory on all machines. So, what we need is: 


\begin{itemize}
\dokuitem  Seperate Development by giving each developer an own Branch
\dokuitem  Distributing of the new code using CVS\dokufootmark{1}-command 'up'
\dokuitem  Easy merging through the CVS\dokufootmark{1}-command 'join'
\end{itemize}
 The first two points are easily done in CVS\dokufootmark{1}. 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 \dokuitalic{Main} and \dokuitalic{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'. 

%% Table analyse:
%%    Numrows: 4
%%    Most Long row size: 38
%%    Choose table mode: tabular
\begin{figure}[h]
\begin{tabular}{llll}
\hline
\multicolumn{2}{|c|}{  Main             }&\multicolumn{2}{c|}{  Nicou            }\\ 
\hline
\multicolumn{1}{|c|}{  server  }&\multicolumn{1}{c|}{  local  }&\multicolumn{1}{c|}{  server  }&\multicolumn{1}{c|}{  local  }\\ 
\hline
\multicolumn{1}{|c|}{  a b c   }&\multicolumn{1}{c|}{  a b c  }&\multicolumn{1}{c|}{  a b c   }&\multicolumn{1}{c|}{  a b c  }\\ 
\hline
\multicolumn{1}{|l|}{ tag: lswN }&\multicolumn{1}{l|}{ }&\multicolumn{1}{l|}{ tag: lswM }&\multicolumn{1}{l|}{ }\\ 
\hline
\end{tabular}
\end{figure}

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

%% Table analyse:
%%    Numrows: 3
%%    Most Long row size: 41
%%    Choose table mode: tabular
\begin{figure}[h]
\begin{tabular}{lllll}
\hline
\multicolumn{1}{|l|}{ }&\multicolumn{1}{l|}{ }&\multicolumn{1}{l|}{ }&\multicolumn{1}{l|}{ }&\multicolumn{1}{l|}{ }\\ 
\hline
\multicolumn{1}{|l|}{ a b' c d }&\multicolumn{1}{l|}{ a b' c d }&\multicolumn{1}{l|}{ }&\multicolumn{1}{l|}{ a b c' e }&\multicolumn{1}{l|}{ a b c' e }\\ 
\hline
\multicolumn{1}{|l|}{ }&\multicolumn{1}{l|}{ }&\multicolumn{1}{l|}{ }&\multicolumn{1}{l|}{ }&\multicolumn{1}{l|}{ }\\ 
\hline
\end{tabular}
\end{figure}

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


\small
\begin{verbatimtab}

SRadio.Nicou> Conventions/synch

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

%% Table analyse:
%%    Numrows: 3
%%    Most Long row size: 44
%%    Choose table mode: tabular
\begin{figure}[h]
\begin{tabular}{lllll}
\hline
\multicolumn{1}{|l|}{ }&\multicolumn{1}{l|}{ }&\multicolumn{1}{l|}{ }&\multicolumn{1}{l|}{ }&\multicolumn{1}{l|}{ }\\ 
\hline
\multicolumn{1}{|l|}{ a b' c d }&\multicolumn{1}{l|}{ a b' c d }&\multicolumn{1}{l|}{ }&\multicolumn{1}{l|}{ a b c' e }&\multicolumn{1}{l|}{ a b' c' d e }\\ 
\hline
\multicolumn{1}{|l|}{ }&\multicolumn{1}{l|}{ }&\multicolumn{1}{l|}{ }&\multicolumn{1}{l|}{ }&\multicolumn{1}{l|}{ }\\ 
\hline
\end{tabular}
\end{figure}

 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:


\small
\begin{verbatimtab}

SRadio.Main> Conventions/synch

\end{verbatimtab}
\normalsize
And we get: 

%% Table analyse:
%%    Numrows: 3
%%    Most Long row size: 47
%%    Choose table mode: tabular
\begin{figure}[h]
\begin{tabular}{lllll}
\hline
\multicolumn{1}{|l|}{ }&\multicolumn{1}{l|}{ }&\multicolumn{1}{l|}{ }&\multicolumn{1}{l|}{ }&\multicolumn{1}{l|}{ }\\ 
\hline
\multicolumn{1}{|l|}{ a b' c d }&\multicolumn{1}{l|}{ a b' c' d e }&\multicolumn{1}{l|}{ }&\multicolumn{1}{l|}{ a b c' e }&\multicolumn{1}{l|}{ a b' c' d e }\\ 
\hline
\multicolumn{1}{|l|}{ }&\multicolumn{1}{l|}{ }&\multicolumn{1}{l|}{ }&\multicolumn{1}{l|}{ }&\multicolumn{1}{l|}{ }\\ 
\hline
\end{tabular}
\end{figure}

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


\small
\begin{verbatimtab}

SRadio.Nicou> Conventions/tag

\end{verbatimtab}
\normalsize
and finally we get this picture: 

%% Table analyse:
%%    Numrows: 3
%%    Most Long row size: 53
%%    Choose table mode: tabular
\begin{figure}[h]
\begin{tabular}{lllll}
\hline
\multicolumn{1}{|l|}{ }&\multicolumn{1}{l|}{ }&\multicolumn{1}{l|}{ }&\multicolumn{1}{l|}{ }&\multicolumn{1}{l|}{ }\\ 
\hline
\multicolumn{1}{|l|}{ a b' c' d e }&\multicolumn{1}{l|}{ a b' c' d e }&\multicolumn{1}{l|}{ }&\multicolumn{1}{l|}{ a b' c' d e }&\multicolumn{1}{l|}{ a b' c' d e }\\ 
\hline
\multicolumn{1}{|l|}{ tag: lswN   }&\multicolumn{1}{r|}{             }&\multicolumn{1}{l|}{ }&\multicolumn{1}{l|}{ tag: lswM }&\multicolumn{1}{l|}{ }\\ 
\hline
\end{tabular}
\end{figure}

 Now we can start again with changing in both branches.


\dokutitleleveltwo{Starting a new Branch}
\label{319c3237dfa10760f701179fd9c0724a}%% 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:


\small
\begin{verbatimtab}

SRadio.Main> cvs tag -b Branch_Brian

\end{verbatimtab}
\normalsize
Then we have to make sure that everything is correctly tagged:


\small
\begin{verbatimtab}

SRadio.Main> Conventions/tag Brian

\end{verbatimtab}
\normalsize
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.


\dokutitleleveltwo{Checking Out for the First Time}
\label{a6c010c801aac0db5b3e02db72296dcf}%% checking_out_for_the_first_time
\label{sec:cvs_first_checkout} It is a good idea to have the following set-up if you're not familiar with CVS\dokufootmark{1}:


\small
\begin{verbatimtab}

brian@radio1: > echo "export CVS_RSH=ssh" >>  /.bashrc
brian@radio1: > echo -e "cvs -q\nup -dP \ncommit -m ''" > /.cvsrc

\end{verbatimtab}
\normalsize
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:


\small
\begin{verbatimtab}

brian@radio1: > cvs -d sradio@lcmpc10.epfl.ch:/home/sradio/cvs co -r
Branch_Brian SRadio
brian@radio1: > mv SRadio SRadio.Brian

\end{verbatimtab}
\normalsize
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.




\dokutitlelevelone{Creating a simple radio}
\label{f8c70f328006a690f0b73d80c39289a0}%% creating_a_simple_radio
\label{f8c70f328006a690f0b73d80c39289a0}%%Start: creating_a_simple_radio => /var/www/html/ipgwww/data/pages/creating_a_simple_radio.txt
\label{cha:simple radio} In this chapter you'll learn how to create a very simple radio consisting of a transmitter and a receiver. You should know the very basics of a digital transmission. For a short introduction in this matter, you can also go and read chapter \ref{cha:signal flow}.

In figure \ref{fig:first_radio} you see the goal of this tutorial: two radios, called \dokuitalic{Master} and \dokuitalic{Client} with the following functions: 


\begin{itemize}
\dokuitem  Master: send the synchronisation, training-sequence and an image
\dokuitem  Client: synchronize, do a channel estimation and decode the image
\end{itemize}
 \begin{figure}
\begin{center}
 		\includegraphics{/var/www/html/ipgwww/data/media/graphviz/0b2dc2363ea44ebc7a7fabd21aa8aa57.ps}
 \end{center}
\caption{\label{fig:first_radio}A very simple radio}
\end{figure}


Both the master and the client can be represented by a simple chain. So it will be very easy to implement these two radios as shown in the rest of this tutorial.

After explaining some more general things about the software-radio, we'll explain first the master, then the client. You can find the basic files with all the basic setup already done in the sub-directory \dokuitalic{Radios/ICS{\textunderscore}Simple} of the SRadio-project. \dokuitalic{Master/radio{\textunderscore}master.c} contais the basic setup of the master and \dokuitalic{Client/radio{\textunderscore}client.c} the basic setup of the client.


\dokutitleleveltwo{General Setup}
\label{c1f632a706cc20daf4becc845fffbe31}%% general_setup
This section is just a very brief introduction to the software-radio. For a more complete overview, follow the references. First some overview of the software-radio, then an explanation of the C-files.


\dokutitleleveltree{Overview}
\label{bce059749d61c1c247c303d0118d0d53}%% overview
As explained in chapter \ref{cha:modes of operation}, the software-radio can be run either in simulation- or in real-time-mode. While it is possible to have both the master and the client on the same computer in simulation mode, this is not possible in real-time mode. The first part of this HOWTO works only in simulation-mode, so you need neither hardware nor two computers to run the examples.

In simulation mode, the master and the client connect to a \dokuitalic{channel-server} which simulates a simple wireless connection with some noise and a fading-channel. Both the master and the client run independently of each other and the only connection is the channel-server. Each one has a complete software-radio environment with a CDB and a SDB (see also \ref{subsec:cdb and sdb}), so that they can communicate only through the channel-server. This corresponds to the real transmission where the two radios can only communicate through the channel.


\dokutitleleveltree{Files}
\label{45b963397aa40d4a0063e0d85e4fe7a1}%% files
Because the master and the client are independent entities, they are put in a seperate directory. In each directory a small template-file can be found that contains the initialisations necessary for the software-radio. For this tutorial, two functions are important: 


\begin{itemize}
\dokuitem  start{\textunderscore}it comparable to the \dokuitalic{main}-function in C-programs or the \dokuitalic{constructor} in a C++-class
\dokuitem  um{\textunderscore}module{\textunderscore}exit which corresponds to the \dokuitalic{destructor}-function in a C++-class.
\end{itemize}
 In the start{\textunderscore}it-function the radio initialises some modules and/or chains (see \ref{subsec:modules and chains}) which are cleaned-up in the um{\textunderscore}module{\textunderscore}exit-function.


\dokutitleleveltwo{Master}
\label{eb0a191797624dd3a48fa681d3061212}%% master
The master needs to send an image, encode it using a spreading-sequence, add a trainig-sequence for the channel estimation and put a synchronisation-signal on top of this, so that the client can synchronise. Looking at figure \ref{fig:first_radio}, we can directly deduce the necessary chain:

\begin{figure}
\begin{center}
 		\includegraphics{/var/www/html/ipgwww/data/media/graphviz/2cc3d077a9c616c4ae830d8154aa543e.ps}
 \end{center}
\caption{  }
\end{figure}


The most simplest way to do that is to create a chain with all the modules inside. In order to do that, open the file for the master in \dokuitalic{Radios/ICS{\textunderscore}Simple/Master/radio{\textunderscore}master.c} and put the following text in the function \dokuitalic{start{\textunderscore}it}: 


\small
\begin{verbatimtab}

  swr_sdb_id img, spread;
  PR( "Setting up send-chain\n" );
  send_ch = swr_chain_create(
    NEW_SPC_VAR( "image_send", img ),
    NEW_SPC( "mapper" ),
    NEW_SPC_VAR( "spread", spread ),
    NEW_SPC( "chest_send" ),
    NEW_SPC( "synch_send" ),
    NEW_SPC( "rrc_complex_send" ),
    NEW_SPC_VAR( "stfa_ics", stfa ),
    CHAIN_END );

\end{verbatimtab}
\normalsize
 For more explanation on the NEW{\textunderscore}* commands, see \ref{subsub:swr_chain_create}. In short we use \dokuitalic{NEW{\textunderscore}SPC} to instantiate a new module and \dokuitalic{NEW{\textunderscore}SPC{\textunderscore}VAR} to instantiate a module and get a reference-id back. Now that this chain is created, we need to tell the STFA\dokufootnote{read
\ref{subsec:stfa} for more information} that this is a transmission-chain. We use the following command: 


\small
\begin{verbatimtab}

  swr_stfa_notice_sdb( stfa, 0, img );

\end{verbatimtab}
\normalsize
 Now everytime the STFA wants to send slot 0, it will call the img-instantiation of the "image{\textunderscore}send"-module. Finally we set up the STFA in transmission-mode and tell the spread-module to use a spreading-factor of two\dokufootnote{which is equivalent to a simple repetition code}: 


\small
\begin{verbatimtab}

  swr_sdb_set_config_int( stfa, "tx", 1 );
  swr_sdb_set_config_int( spread, "factor", 2 );

\end{verbatimtab}
\normalsize
 Now we're ready to start the STFA: 


\small
\begin{verbatimtab}

  swr_stfa_go( stfa );

\end{verbatimtab}
\normalsize
 That's it for the start{\textunderscore}it function. Because we use the \dokuitalic{send{\textunderscore}ch} and the \dokuitalic{stfa} globally, we need to define these above the start{\textunderscore}it-function like this: 


\small
\begin{verbatimtab}

struct chain_t *send_ch;
swr_sdb_id stfa;

\end{verbatimtab}
\normalsize
 And, last but not least, we need to clean up the chain in case the radio gets stopped. This is done by inserting the following lines at the end of the \dokuitalic{um{\textunderscore}module{\textunderscore}exit}-function:


\small
\begin{verbatimtab}

  if ( stfa ){
    PR( "Stopping the STFA$\backslash$n" );
    swr_stfa_stop( stfa );
    PR( "Deleting Sending-chain$\backslash$n" );
    swr_chain_destroy( send );
  }

\end{verbatimtab}
\normalsize

\dokutitleleveltree{Testing the Master}
\label{09bb5a5fc2ce292344d239aacb0b5fee}%% testing_the_master
Now that the master is written, we can test it. First of all, make sure that you can compile it, using


\small
\begin{verbatimtab}

make

\end{verbatimtab}
\normalsize
and that there are neither warnings nor errors. Then you can call


\small
\begin{verbatimtab}

make show_local

\end{verbatimtab}
\normalsize
and if everything is OK, you should see a window coming up that displays the STFA as a horizontal white bar and the chain attached to it. Right-clicking on the \dokuitalic{image{\textunderscore}send}-module you can chose \dokuitalic{Display Data} and then \dokuitalic{picture} which will pop up a window with the picture sent in it. Keeping this window and right-clicking on \dokuitalic{rrc{\textunderscore}complex{\textunderscore}send}, then \dokuitalic{Display outputs} and \dokuitalic{port{\textunderscore}out{\textunderscore}0} shows the output of this chain in complex format. In this new window you can click on \dokuitalic{Complex} and chose \dokuitalic{FFT} to see a fast-fourier transform of the same output. You can also change the behaviour of some of the modules. For example you can change the \dokuitalic{factor}\dokufootnote{this is the spreading-factor or the
spreading-length of the code} of the \dokuitalic{spread}-module. Right-click on the \dokuitalic{spread}-module and chose \dokuitalic{Change config}. Now you can increase or decrease the \dokuitalic{factor}-value. If you still have the image-window open, you can see how the image changes when increasing or decreasing the \dokuitalic{factor}-value. The next subsection explains why this happens.


\dokutitleleveltree{Slots and Blocks in the Software-Radio}
\label{2234e6b94447d5b1731e242ab948a3f1}%% slots_and_blocks_in_the_software-radio
This is a small excurse in the internals of the software-radio. It's goal is to give you some more understanding of how our implementation works. It is not elemental but quite useful to understand the rest of the software-radio.

The software-radio works with fixed blocks of data. Everything that goes over the air has to fit into one slot. In the current implementation, a slot is of length 2560 symbols\dokufootnote{this is an artefact of the first
UMTS-implementation. You can change the slot-length in multiples of 128
symbols}. Every time the software-radio wants to send a slot, the output of the chain has to fit in 2560 symbols.

Starting from the STFA, the software-radio calculates the maximum size available by asking each module how much symbols it needs: 

$\frac{1}{n}$
$\frac{2078}{n}$
$*2$
$\frac{4156}{n}$
%% Table analyse:
%%    Numrows: 6
%%    Most Long row size: 34
%%    Choose table mode: tabular
\begin{figure}[h]
\begin{tabular}{llll}
\hline
\multicolumn{1}{|l|}{module}&\multicolumn{1}{l|}{use}&\multicolumn{1}{l|}{symbols}&\multicolumn{1}{l|}{left}\\ 
\hline
\multicolumn{1}{|l|}{stfa}&\multicolumn{1}{l|}{guard-period}&\multicolumn{1}{l|}{90}&\multicolumn{1}{l|}{2470}\\ 
\hline
\multicolumn{1}{|l|}{synch{\textunderscore}send}&\multicolumn{1}{l|}{synchronisation}&\multicolumn{1}{l|}{256}&\multicolumn{1}{l|}{2214}\\ 
\hline
\multicolumn{1}{|l|}{chest{\textunderscore}send}&\multicolumn{1}{l|}{training-sequence}&\multicolumn{1}{l|}{136}&\multicolumn{1}{l|}{2078}\\ 
\hline
\multicolumn{1}{|l|}{spread}&\multicolumn{1}{l|}{spreading-sequence}&\multicolumn{1}{l|}{}&\multicolumn{1}{l|}{}\\ 
\hline
\multicolumn{1}{|l|}{mapper}&\multicolumn{1}{l|}{bit-to-symbols}&\multicolumn{1}{l|}{}&\multicolumn{1}{l|}{bits}\\ 
\hline
\end{tabular}
\end{figure}

 This means that the image{\textunderscore}send-module has a variable-sized output that can vary from 4156 to $\frac{4156}{32}=129$
 bits\dokufootnote{The spreading-module
has a maximum spreading-length of 32}, depending on the spreading-factor chosen. Every time the output-size of the image{\textunderscore}send-module changes, it adjusts the image-size so that it fits in the given place.

For this reason you see the image changing when you change the spreading-factor of the spreading-module.


\dokutitleleveltwo{Client}
\label{62608e08adc29a8d6dbc9754e659f125}%% client
Looking at figure \ref{fig:first_radio} we can see that we have to implement the following chain:

\begin{figure}
\begin{center}
 		\includegraphics{/var/www/html/ipgwww/data/media/graphviz/afa0533f46e93ea0ef6a8c42d241d696.ps}
 \end{center}
\caption{  }
\end{figure}


There are two small subtelties when implementing this receiver-chain: first, we put the \dokuitalic{synch{\textunderscore}rcv}-module in front of the \dokuitalic{rrc{\textunderscore}rcv}-module. Looking at the master, we'd expect to first do the rrc-reception and then the synchronisation. But as the rrc{\textunderscore}rcv-module downsamples by a factor of two, it is better to do the synchronisation at the higher sample-rate, in order to have a more exact synchronisation.

Second, the actual module-names are quite long: sync{\textunderscore}rcv is called \dokuitalic{synch{\textunderscore}complex{\textunderscore}ics{\textunderscore}rcv} and rrc{\textunderscore}rcv is called \dokuitalic{rrc{\textunderscore}complex{\textunderscore}ics{\textunderscore}rcv}. This is due to the development-process of the software-radio and the wish to keep old things running.

Besides these small details, the client is built more or less in the same way as the server. All these lines go in \dokuitalic{Radios/ICS{\textunderscore}Simple/Client/radio{\textunderscore}client.c}. Before the \dokuitalic{start{\textunderscore}it}-function, we declare the \dokuitalic{stfa} and the \dokuitalic{rcv{\textunderscore}ch}:


\small
\begin{verbatimtab}

swr_sdb_id stfa;
struct chain_t *rcv_ch;

\end{verbatimtab}
\normalsize
In the \dokuitalic{start{\textunderscore}it}-function, we declare the needed variables and the reception-chain:


\small
\begin{verbatimtab}

  swr_sdb_id synch, mafi, despread, slicer;
  rcv_ch = swr_chain_create( NEW_SPC_VAR( "stfa_ics", stfa ),
    NEW_SPC_VAR( "synch_complex_ics_rcv", synch ),
    NEW_SPC( "rrc_complex_ics_rcv" ),
    NEW_SPC_VAR( "chest_rcv", mafi ),
    NEW_SPC_VAR( "despread", despread ),
    NEW_SPC_VAR( "slicer", slicer ),
    NEW_SPC( "image_rcv" ),
    CHAIN_END );

\end{verbatimtab}
\normalsize
This chain is the same as in figure \ref{fig:first_radio} and described above. Some of the modules need some configuration so that the radio works correctly. We have to do these things: 


\begin{itemize}
\dokuitem  Gain: adjust the gain of the RF-cards, so that the cards don't saturate
\dokuitem  Synchronisation: tell the module the id of the STFA so it can adjust for the desynchronisation
\dokuitem  Despreading: set the despreading-factor to 2
\dokuitem  Matched Filter: calculate 8 taps and align them
\dokuitem  Slicer: set the id of the matched filter so that it can know the amplitude of the signal
\end{itemize}
 All these values are in the configurable part of the modules, so we can set them using the swr{\textunderscore}sdb{\textunderscore}set{\textunderscore}config*-functions:


\small
\begin{verbatimtab}

  swr_sdb_set_config_int( stfa, "attn_tx", 31 );
  swr_sdb_set_config_int( stfa, "attn_rx", 15 );
  swr_sdb_set_config_int( synch, "stfa_id", stfa );
  swr_sdb_set_config_int( despread, "factor00", 2 );
  swr_sdb_set_config_int( mafi, "calc_taps", 8 );
  swr_sdb_set_config_int( mafi, "align", 1 );
  swr_sdb_set_config_int( slicer, "mafi_id", mafi );

\end{verbatimtab}
\normalsize
Now everything is ready to start the STFA:


\small
\begin{verbatimtab}

  swr_stfa_go( stfa );

\end{verbatimtab}
\normalsize
We need to do some initialisation, just in case something will go wrong. Insert this line in the beginning of the function \dokuitalic{um{\textunderscore}module{\textunderscore}init}:


\small
\begin{verbatimtab}

  stfa = 0;

\end{verbatimtab}
\normalsize
And at the end we need to clean things up, so insert these lines at the end of \dokuitalic{um{\textunderscore}module{\textunderscore}exit}:


\small
\begin{verbatimtab}

  if ( stfa ){
    PR( "Stopping stfa$\backslash$n" );
    swr_stfa_stop( stfa );
    PR( "Destroying rcv-chain$\backslash$n" );
    swr_chain_destroy( rcv_ch );
  }

\end{verbatimtab}
\normalsize

\dokutitleleveltree{Testing the Client}
\label{e09fb5329042e13741195558663ff7e7}%% testing_the_client
Compile it with \dokuitalic{make} and correct eventual errors. Once everything compiles nicely, you can go in the directory \dokuitalic{Radios/ICS{\textunderscore}Simple} and type


\small
\begin{verbatimtab}

make show_mc

\end{verbatimtab}
\normalsize
This will start the master, then the client and will bring up the visualize-tool so that you can see the modules in action. Once the visualize-tool is started, you can see that there are now two tabs, one for the master and the other for the client. Clicking on these tabs you can switch between the two radios.


\dokutitleleveltree{Testing the transmission}
\label{7314d0b99d39e190a6e3562f36ecff55}%% testing_the_transmission
If everything up to here works as described, congratulations. You just finished your first very simple radio-transmission using the software-radio. While running the master and the client, you can now visualize different modules and change the configuration-parameters, in order to see what happens.


\dokutitleleveltree{Synchronisation}
\label{85ceb46695acb5dfcc7a806904a25365}%% synchronisation
A small word on synchronisation: the implementation we did in this tutorial is the most simplest possibility. Every frame the synchronisation-module will search for a synchronisation-signal. If it decides that there is no synchronisation, it shifts half a slot and will try again in the next frame.

The worst-case scenario is that the synchronisation-signal is just on the opposite side of the searching-direction, which will make the synchronisation-module searching the whole frame. In real time, one frame corresponds to 30ms and holds 15 slots, so that it will be searched completely in 1sec.

For a radio-application, 1 second is quite a long time. For this reason, a second method exists which is a bit more complicated but finds the synchronisation-signal on the first go. A \dokuitalic{macro-module} called \dokuitalic{macro{\textunderscore}synch{\textunderscore}ics} attaches a synchronisation-module to each slot of the stfa. Once a whole frame is received, it loops over all synchronisation-modules and choses the one with the strongest synchronisation-signal, discarding all others.

This allows the software-radio to synchronise in much more efficient way. As this method includes callback-functions and handling the macro-module, we decided to go the easy way and just scan the whole frame.


\dokutitleleveltwo{RF-transmission}
\label{d655a5c3c9c6e91706545e8f0df17f00}%% rf-transmission
Now everything should be ready to be able to transmit over the air. Once the simulation works, there are usually no big bugs left that can hinder the test over the air.

As you will have to transmit from one computer to the other, the code needs to be installed on two computers where each computer has the appropriate hardware installed. Once this is done, it is usually more efficient to work on one computer only and to \dokuitalic{ssh} in the other computer and run the software-radio remotely. This gives you the advantage of having all the output on one screen.

To start the master, simply go into the \dokuitalic{Radios/ICS{\textunderscore}Simple/Master}-directory and call


\small
\begin{verbatimtab}

make rf_show

\end{verbatimtab}
\normalsize
which should start the real-time part of the software-radio and show up the transmission-window. On the other computer, go into the \dokuitalic{Radios/ICS{\textunderscore}Simple/Client} directory and issue the same command:


\small
\begin{verbatimtab}

make rf_show

\end{verbatimtab}
\normalsize
If all goes well, you should have now two windows where one shows the master and the other the client. You can now play around with the values to see how the software-radio reacts. Interesting configuration-parameters include the attn{\textunderscore}tx on the master-side, the attn{\textunderscore}rx on the client side. Both can be found in the stfa, the horizontal white line in the middle of the window.

Other things to experiment with is the calc{\textunderscore}taps of the chest{\textunderscore}rcv-module or the factor and sequence configuration of the spread and despread-module.


\dokutitleleveltree{Going Further}
\label{40058fb1f2cdb6176ca23c9692c4a28f}%% going_further
Now that you have this simple radio running, it is possible to change the spreading-module with something else, for example a convolution-module or even an ldpc-module. You can also add other chains to the stfa in a similar manner than the ones we did. If you do so, don't forget that you don't need a synchronisation-module anymore on the additional chains. One synchronisation-module per frame is enough. 

\part{Practice}




\dokutitlelevelone{Introduction}
\label{8800e1c9b3e22c44ba59a34db3fe4841}%% introduction
\label{8800e1c9b3e22c44ba59a34db3fe4841}%%Start: introduction => /var/www/html/ipgwww/data/pages/introduction.txt
 This document started out as a work-description on what has been going on with the software-radio. It now is a reference for the RF-interface of the software-radio as well as a setup-guide for the hardware-part of the software-radio. For the software-part, see the document "A tutorial to the software-radio".


\dokutitleleveltwo{Motivation}
\label{8b20d3634bbbbf95c71aa00ea43b1dca}%% motivation
 During Summer/Fall 2004 different projects have been done on the software-radio that asked for special implementations on the level of the ICS-cards. Four useful branches co-existed: 


\begin{enumerate}\dokuitem  Normal MIMO at 2.4GHz with 1MS/s
\dokuitem  Radar-application at 2.4GHz with 100kS/s
\dokuitem  802.11-reception at 2.4GHz with 20MS/s
\dokuitem  GPS-reception at IF of 24MHz and 4MS/s at 32 bits per complex sample
\end{enumerate}
 1-3 were done using the normal FPGA-programm, while 4 is only possible with a rewritten FPGA. This is due to the fact that the PCI can't transfer the data representing a raw GPS-signal. The rewritten FPGA-program represents one sample using 32 bits, whereas the original FPGA-program represents one sample using 128 bits.

In order to have a program that can handle all these situations, a new interface to the ICS-cards was built. The goal of this interface is to set the basic parameters of the ICS-cards in a more user-friendly way. These parameters are: 


\begin{itemize}
\dokuitem  Sampling-frequency
\dokuitem  Bandwith
\dokuitem  Data-type
\dokuitem  Number of channels
\dokuitem  Center-frequency
\dokuitem  Detect the FPGA-programm type
\end{itemize}
 All frequencies are given in Hz and the sampling-rates in Complex Samles per second (CSs). 1 CS corresponds to 2 Real Samples.


\dokutitleleveltwo{Intended reader}
\label{e0d74bcd6ba0983746674bfadecd3aea}%% intended_reader
 This document has been written to keep track of the changes in the programming and to help further engineers keeping track of what is going on. Depending on which part of the document you're interested in, the necessary background differs. In order to build the different target applications, you should have good knowledge in informatics and a good understanding of the UNIX-shell. For the reference-part you have to be a good programmer and have some background of the software-radio. A good start is "A tutorial on the software-radio".


\dokutitleleveltwo{Parts}
\label{78f0805fa8ffadabda721fdaf85b3ca9}%% parts
 The different parts in this document include: 


\begin{itemize}
\dokuitem  Motivation what you are reading
\dokuitem  Usecases describes the four goals and how to test them
\dokuitem  Subsystems which gives an overview of the different parts of the software-radio hardware
\dokuitem  Interface is the main part and describes in detail the new functions used to interact with the hardware
\dokuitem  Tidbits collects different thoughts about the project that came up during the writing of this document
\end{itemize}

\dokutitleleveltwo{Conventions}
\label{8b16228fe06418aeaeccfa0af9f10323}%% conventions

\dokutitleleveltree{Directories}
\label{bd1e333d1166f18893b2bbeba10229a3}%% directories
 All given directories are relative to your SRadio.\dokuitalic{Branch}-directory. The position of this branch is marked \dokuitalic{{\textdollar}SRADIO}. This has to be installed for you by the system administrator, as well as a CVS\dokufootnote{Concurrent Versions System}-access to the source-code. So if your system-administrator installed a branch under


\small
\begin{verbatimtab}

/home/foo/SRadio.Bar

\end{verbatimtab}
\normalsize
and a command asks you to


\small
\begin{verbatimtab}

cd $SRADIO/Test/Radar

\end{verbatimtab}
\normalsize
Then this means you have to enter the following directory:


\small
\begin{verbatimtab}

/home/foo/SRadio.Bar/Test/Radar

\end{verbatimtab}
\normalsize

\dokutitleleveltree{Commands}
\label{5f6bc08c46cee6f21bfcdd08aff6e8aa}%% commands
 Commands are written in typewriter-code, like this:


\small
\begin{verbatimtab}

cvs -d sradio@lcmpc10.epfl.ch:/home/sradio/cvs \
  co -b Branch_Report SRadio

\end{verbatimtab}
\normalsize
Special meanings are explained in brackets, for example:


\small
\begin{verbatimtab}

make rf_tail
[ wait for 5 seconds ]
make rmall

\end{verbatimtab}
\normalsize

\dokutitleleveltree{Radio-platforms}
\label{e3502c2133f44d1b94e074469ac532b0}%% radio-platforms
 There are two radio-platforms, called \dokuitalic{radio1} and \dokuitalic{radio2}. The work represented in this document requires root-privileges to be run, so ask your system-administrator for the root-password and how to log in.

If you are in the local network of the software-radio, you can login to \dokuitalic{radio1} and \dokuitalic{radio2} with


\small
\begin{verbatimtab}

ssh root@radio1

\end{verbatimtab}
\normalsize
or


\small
\begin{verbatimtab}

ssh root@radio2

\end{verbatimtab}
\normalsize
 


\dokutitlelevelone{Test Configurations}
\label{b087a47662fcd995b37ac88f5f4890c2}%% test_configurations
\label{b087a47662fcd995b37ac88f5f4890c2}%%Start: test_configurations => /var/www/html/ipgwww/data/pages/test_configurations.txt
 This section describes the sample configurations. Both soft- and hardware-setup is described for each configuration. It is a good starting point for new users.

The following configurations are described here: 


\begin{itemize}
\dokuitem  GPS for the reception and storage of a GPS-signal
\dokuitem  Radio demonstrates a simple send/receive-setup
\dokuitem  Radar is a simple game using radar-measurements of a moving ball
\dokuitem  WLAN captures one or more 802.11-packets
\end{itemize}

\dokutitleleveltwo{Setup}
\label{a0f848942ce863cf53c0fa6cc684007d}%% setup
 This subsection contains some general overview of the different hardware-subsystems.


\dokutitleleveltree{RF-cards}
\label{3145a2dba9a2e0656b5d37627e0db824}%% rf-cards
 Fig. \ref{fig:RF-cards} shows the input/output connectors of the RF cards (power supply omitted).

\begin{figure}
\begin{center}
\includegraphics{/var/www/html/ipgwww/lib/plugins/tmp/texitimages/texitLa2e7S.ps}\end{center}
\caption{\label{fig:RF-cards}The important connections on a RF-card}
\end{figure}



\dokutitleleveltree{Rohde \& Schwarz}
\label{f76839d46c4e0e67e3d314680cc96ea4}%% rohde_schwarz
 All settings given in the figures start from a presetted state of the signal-generator or -analyzer. You find a button labeled \dokuitalic{Preset} that sets the machine into a well-known state.


\dokutitleleveltree{ICS-cards}
\label{43317a7e7fe8768dca2ade79219d735f}%% ics-cards
 In the following picture (TODO) you can see the ICS-cards on the back of the computer. All the input and output-labels are visible.


\dokutitleleveltree{FPGA}
\label{a5643066c7a784ec29b50db0361ec90f}%% fpga
 As described in section \ref{sec:FPGA}, the FPGA can be programmed with two versions of the code: one for the GPS-reception, and another one for everything else. Please be sure to chose the appropriate code, or the given application will not work.

Refer to section \ref{sec:FPGA} on how to reprogram the PFGA.


\dokutitleleveltree{Power supply}
\label{5b707c19ace588b0304807d6fff7b0d5}%% power_supply
 Wrong settings of the power-supply may destroy the attached hardware, so take care and be sure to follow these instructions: 


\begin{enumerate}\dokuitem  Switch up 1 \& 2
\dokuitem  Connect the power supply
\dokuitem  Switch down 1
\dokuitem  Adjust voltage and current using 3 \& 4
\dokuitem  Switch down 2
\end{enumerate}



\dokutitleleveltwo{GPS}
\label{11648e4e66e7ed6a86cb7f1d0cf604fe}%% gps
\label{11648e4e66e7ed6a86cb7f1d0cf604fe}%%Start: gps => /var/www/html/ipgwww/data/pages/gps.txt
 For a clean reception of a GPS signal, it is advised to have a view as wide as possible of the open sky. Chose a roof-top or a wide field with no obstruction. Then you can start with the reception of a 60-second piece of data:

Before doing so, test this given setup with a much shorter sequence, 2 seconds, as described below. Once everything is working all right, use the longer sequence.


\dokutitleleveltree{Hardware-setup}
\label{da7c1616ba275796dc053fb949071982}%% hardware-setup
 The setup of the hardware for the GPS-acquisition can be seen in Figure \ref{cap:GPS-setup}. If you extend the cable of the GPS-antenna, the received signal may be too weak!

\begin{figure}
\begin{center}
\includegraphics{/var/www/html/ipgwww/lib/plugins/tmp/texitimages/texitaZwFyn.ps}\end{center}
\caption{\label{GPS-setupcap:GPS-setup}}
\end{figure}



\dokutitleleveltree{Software-setup}
\label{bcad5fe78046485ed8c542e951bd6f51}%% software-setup
 First you have to re-program the FPGA, so that the correct code is loaded in the ICS-card. Refer to Section \ref{sec:FPGA} on how to do this. For a first test, it is advised to use only a short testing sequence, see the paragraph below. This short sequence can be used to test whether enough satellites are visible. Once the FPGA is repgrammed do the following:


\small
\begin{verbatimtab}

cd
<latex>SRADIO/Test/GPS
make rf_tail

[ wait for the message "*** Acquisition done ***" ]

../../Tools/Dbg/dbg 2 0 > ../../Matlab/GPS/gps_yymmdd_hhmm.dat

\end{verbatimtab}
\normalsize
Where \dokuitalic{yymmdd{\textunderscore}hhmm} stands for the current date and time. This is just a convenient way to remember when the samples were collected. Be aware that each second of measurement takes about 25MBytes. So 60 seconds of measurement take 1.5GByte!

Then you can check which satellites are visible from the antenna location using using the program in \dokuitalic{{\textbackslash}{\textdollar}SRADIO/Matlab/GPS}/:


\small
\begin{verbatimtab}

matlab -nojvm -nosplash
[ wait for Matlab to start up ]
acquisition( 'gps_yymmdd_hhmm.dat', 100000 );

\end{verbatimtab}
\normalsize
this should show you a plot with a noise-floor around $10000$
 and a number of points sticking distinctively out to $14000-20000$
. Then chose the highest point and run the following command:


\small
\begin{verbatimtab}

acquisition_scan( 'gps_yymmdd_hhmm.dat', 100000, #sat# );

\end{verbatimtab}
\normalsize
where \dokuitalic{sat} corresponds to the highest peak seen in the previous plot.


\dokutitlelevelfour{Short testing sequence}
 Before getting a 60-second piece of data, it is adviseable to test it on a short sequence to see whether enough satellites are visible or if there is a problem with the setup.

In the file \dokuitalic{{\textbackslash}{\textdollar}SRADIO/Test/GPS/test{\textunderscore}gps.c} adjust the \dokuitalic{buffer{\textunderscore}len}:


\small
\begin{verbatimtab}

  // Now buffer_len is in seconds of recording
  swr_sdb_set_config_int( gps, "buffer_len", #2# );

\end{verbatimtab}
\normalsize
Now the radio will only record 2 seconds of data which will be much shorter to write to the disk using the above-mentioned method.

 


\dokutitleleveltwo{Radio system}
\label{eecdb28db58d27a3ef51fcc4fa6aecf7}%% radio_system
\label{eecdb28db58d27a3ef51fcc4fa6aecf7}%%Start: radio_system => /var/www/html/ipgwww/data/pages/radio_system.txt
\label{sub:Radio-system}

The first goal of the software-radio was to enable a two-way transceiver on a 2.4GHz link. Use the setup described here:


\dokutitleleveltree{Hardware-setup}
\label{da7c1616ba275796dc053fb949071982}%% hardware-setup
 For a radio transmission, the setup in Figure \ref{cap:Radio-setup} must be done on both radios. It is necessary to have frequency doubler exactly as shown in the figure and not attached to the output of the 8-way splitter, as one may try to do to get rid of the 2-way splitter. Otherwise the clock-signal for the ICS-554 card would be too weak.

\begin{figure}
\begin{center}
\includegraphics{/var/www/html/ipgwww/lib/plugins/tmp/texitimages/texitxhWHwU.ps}\end{center}
\caption{\label{cap:Radio-setup}Radio-setup}
\end{figure}



\dokutitleleveltree{Software-setup}
\label{bcad5fe78046485ed8c542e951bd6f51}%% software-setup
 In order to be sure that the STD-software is loaded in the FPGA, process as described in section \ref{sec:FPGA}. If that is not the case, reprogram the FPGA with the STD-software.

The software needs to be run on both radios, \dokuitalic{radio1} and \dokuitalic{radio2}. On one radio you have to run the sender (BS), on the other radio the receiver (MS\dokufootnote{Microsoft}). To start the sender, run the following commands:


\small
\begin{verbatimtab}

cd $SRADIO/Radios/Image/BS

make rf_show

\end{verbatimtab}
\normalsize
For the receiver you have to log in to the other radio and run the following commands:


\small
\begin{verbatimtab}

cd $SRADIO/Radios/Image/MS

make rf_show

\end{verbatimtab}
\normalsize
on the receiver side. If it doesn't work, go through the following checklist: 


\begin{itemize}
\dokuitem  all cables correctly connected
\dokuitem  power is applied to all elements (50MHz clock and RF-cards)
\dokuitem  RF-cards are connected with the right flatband-connector
\dokuitem  Using the Rohde {\textbackslash}\& Schwarz signal analyzer to check for a singal at 2.38GHz
\end{itemize}
 


\dokutitleleveltwo{Radar-system}
\label{1f006088f56c6d16bdde1b8c9c11d62c}%% radar-system
\label{1f006088f56c6d16bdde1b8c9c11d62c}%%Start: radar-system => /var/www/html/ipgwww/data/pages/radar-system.txt
 The radar-system uses only one radio-platform, and the setup is similar to \ref{sub:Radio-system}.


\dokutitleleveltree{Hardware-setup}
\label{da7c1616ba275796dc053fb949071982}%% hardware-setup
 For this setup, the duplicator is not needed, and only two RF-cards are necessary. Align the two antennas, so that they point in the direction of the object. If possible, the player should be behind the antennas, so that his movement is hidden to the radar. Else it is difficult to tell apart the movement of the player with the movement of the object.

\begin{figure}
\begin{center}
\includegraphics{/var/www/html/ipgwww/lib/plugins/tmp/texitimages/texitejLOru.ps}\end{center}
\caption{\label{cap:Radar-system}Radar-system}
\end{figure}



\dokutitleleveltree{Software-setup}
\label{bcad5fe78046485ed8c542e951bd6f51}%% software-setup
 Be sure to have the correct code loaded into the FPGA, else refer to \ref{sec:FPGA} on how to program the correct code.

When everything is set up, you can start the radio on the software-platform:


\small
\begin{verbatimtab}

cd \$SRADIO/Test/Radar
make rf_tail

\end{verbatimtab}
\normalsize
Then, on a computer connected to the software-platform, connect the camera, make sure it is detected, and run:


\small
\begin{verbatimtab}

cd \$SRADIO/Tools/PlayRadar
./run

\end{verbatimtab}
\normalsize
Eventually you have to adjust the following two variables:


\begin{lyxlist}{00.00.0000}

\item [REMOTE]points to the software-radio platform


\item [RADIO{\textunderscore}DIR]is the remote directory

\end{lyxlist}


\dokutitleleveltree{Camera-setup}
\label{83148899b3c94c7907bc199383514f75}%% camera-setup
 For this radar-system you can have a camera attached to the computer, so that the different people using the system can be shown live! Unfortunatly, this requires some setup to your computer. The source code for the driver can be found under:


\small
\begin{verbatimtab}

http://www.saillard.org/linux/pwc/debian/

\end{verbatimtab}
\normalsize
and once it is installed, things should run nicely.


\dokutitleleveltree{Amplitude settings}
\label{519a4f26c5248446b371ae6042024a56}%% amplitude_settings
 The amplitude settings are done in case the two antennas are 1m apart and on the same height, pointing in the same direction. If you chose to use them in a different setting, it can be necessary to adjust the values \dokuitalic{attn{\textunderscore}rx} and \dokuitalic{attn{\textunderscore}tx} in the file \dokuitalic{{\textbackslash}{\textdollar}SRADIO/Test/Radar/test{\textunderscore}radar.c} to more convenient values. Lower values mean lower attenuations. So if you put the antennas further apart, it may be useful to chose a lower value for \dokuitalic{attn{\textunderscore}rx}.

You can also run


\small
\begin{verbatimtab}

cd \$SRADIO/Test/Radar
make rf_show

\end{verbatimtab}
\normalsize
and use the configuration-window from the \dokuitalic{radar{\textunderscore}rf}-module while looking at the output of \dokuitalic{radar{\textunderscore}rf} and the \dokuitalic{fft}-stats of the \dokuitalic{radar{\textunderscore}fft}-module. Once you find a good pair of values where the output shows a dotted circle and the fft shows a clean peak, copy these values to \dokuitalic{test{\textunderscore}radar.c} and re-run it.

 


\dokutitleleveltwo{WLAN}
\label{548edac4167de2a8b78ee2be17022f7f}%% wlan
\label{548edac4167de2a8b78ee2be17022f7f}%%Start: wlan => /var/www/html/ipgwww/data/pages/wlan.txt
 The goal is to aquire a part of a WLAN-signal and to decode the most important bits.


\dokutitleleveltree{Hardware-setup}
\label{da7c1616ba275796dc053fb949071982}%% hardware-setup
 For this test, take a wireless access point and set it to channel 6 at a center frequency of 2437MHz. This takes care of EPFLs network that is tuned to channel 1 and 12 at 2412MHz and 2467MHz. The bandwith of the signal is 22MHz.

The setup can be seen in fig. \ref{cap:WLAN-setup}.

\begin{figure}
\begin{center}
\includegraphics{/var/www/html/ipgwww/lib/plugins/tmp/texitimages/texitzt0la7.ps}\end{center}
\caption{\label{cap:WLAN-setup}WLAN-setup}
\end{figure}



\dokutitleleveltree{Software-setup}
\label{bcad5fe78046485ed8c542e951bd6f51}%% software-setup
 If you used the GPS beforehand, you have to re-program the FPGA first. For this, refer to \ref{sec:FPGA}. Once this is done, you can start the aquisition:


\small
\begin{verbatimtab}

cd \$SRADIO/Test/WLAN
make rf_tail
../../Tools/Dbg/dbg 2 0 > ../../Matlab/WLAN/wlan_capture.dat

\end{verbatimtab}
\normalsize
Then you can use the programs in \dokuitalic{{\textbackslash}{\textdollar}SRADIO/Matlab/WLAN} to decode the received WLAN-signal.

\part{Future thoughts}




\dokutitlelevelone{STFA}
\label{adebc2516025b7bd604b0cfcfa740885}%% stfa
\label{9ef73f883d658c9f954cf1213be0313a}%%Start: future_thoughts => /var/www/html/ipgwww/data/pages/future_thoughts.txt
The STFA being a complex module and having evolved over two years, it would be a good idea to re-write it once completely. Here are some ideas on what should be mended and what thoughts should go into a re-structuration of the STFA.


\dokutitleleveltwo{Antenna}
\label{f212100e38f782e152ebfab712a0e6ec}%% antenna
The antenna should be a module on its own with an output for the received samples and an input for the sent samples. These two ports should then be connected to the stfa. Advantages: 


\begin{itemize}
\dokuitem  Configuration If for a given antenna we have special parameters, we can define them as easily as in any module
\dokuitem  Clarification It gives a more constant concept in the software-radio
\dokuitem  Universality For the moment the software-radio is very TDD-based with the STFA. If the antenna is really an independant module, it would be much more easy to implement other stuff
\end{itemize}

\dokutitleleveltwo{Chains}
\label{99469f92ab96d54efce3d605a4bb4fbe}%% chains
\label{future_stfa_chains} The way chains are linked to the STFA is very kludgy. While things are quite OK for RX-chains, it is really not optimal for TX-chains. Consider figure \ref{fig:stfa_tx_kludge} where on the left-hand side you see the actual implementation. The user has to define which modules have to be called at which moment with two function-calls like:


\small
\begin{verbatimtab}

swr_stfa_notice_sdb( stfa, 2, source1 );
swr_stfa_notice_sdb( stfa, 5, source2 );

\end{verbatimtab}
\normalsize
\begin{figure}
\begin{center}
img /var/www/html/ipgwww/data/media/stfa{\textunderscore}tx{\textunderscore}kludge.ps\end{center}
\caption{\label{fig:stfa_tx_kludge}Actual and proposed design of the TX-chain alertion}
\end{figure}


In order to simplify things and thus taking away possible sources of error, it would be much better, if the STFA would consider the chains on its own, like show in the right-hand part of the figure.

For the TX1-chain, not much would change, only the two above-mentioned function-calls could be left out, because the STFA would call the RRC-module with a message like \dokuitalic{SUBS{\textunderscore}MSG{\textunderscore}PRODUCE{\textunderscore}DATA}. The RRC-module in turn would call the Map-module, which would call the Source1-module. Then, the Source1-module produces some data, and everything is like before.

For the TX2-chain, the distribution of the time of calculation would even be more uniform. If you consider the left-hand side, all the calculations for all the modules is done during slot 3 and 4, even though about half of the calculations are not needed before slot 7! Now, if the STFA would be smart enough to not only call the modules with a message \dokuitalic{SUBS{\textunderscore}MSG{\textunderscore}PRODUCE{\textunderscore}DATA}, but also tag the modules passed this way, only the necessary calculations would be carried out.

So, at the beginning of slot 3, the RRC would be notified with \dokuitalic{SUBS{\textunderscore}MSG{\textunderscore}PRODUCE{\textunderscore}DATA} and tagged active. Then the Map-, Split-, and finally the Source2-module would be notified. Once the Source2-module produced its data, the inverse way will be taken. An important point is to note that the Split-module produces both branches of data, but that only the left branch is followed.

Then, at the beginning of slot 5 \dokufootnote{Coincidence: this is the same slot
as the result of the left branch}, the RRC of slot 7 would be notified, which would notify the Map-module, which would see that it has some data to process, and stop the notification of further modules. It then processes the data, hands it to the RRC, which processes its data, too, and hands it to the STFA.


\dokutitleleveltree{Implementation}
\label{b6fa15360b4cdce4806bf9a0580c8f0f}%% implementation
In fact, it is not really necessary to tag the data. Each module could just 


\begin{itemize}
\dokuitem  Check inputs for whether all necessary inputs are filled with data
\dokuitem  Notify upper modules if this is not the case
\dokuitem  Process the data
\end{itemize}
 The idea is that the notification of the upper modules happens synchronously, that is, the notification only returns once it has been carried out. The module can then assume that the data is available.

There are a lot of special cases, just a few here: 


\begin{itemize}
\dokuitem  Multiple inputs of a module, where one or more may be inactive, that is, not connected
\dokuitem  Loops for creating incremental coding
\end{itemize}

\dokutitlelevelone{Visualize}
\label{f279a48f784b90100d413ca55dfc9bfd}%% visualize
 Reading through the reference-part of the visualize-tool, one gets the impression that this tool has been glued together (like oh so many others) more randomly than anything else. Well, unfortunatly, this is true. One project would be to re-design the classes of this tool, and then re-write a more nice version of it.

 The steps to do so could include the following: 


\begin{itemize}
\dokuitem  Understand and look at the existing code. Using a tool like Umbrello, one can get quite fast a basic understanding of which classes use which classes.
\dokuitem  Design a new class-model, where each class has a well-designed purpose.
\dokuitem  Rewrite the whole tool, doing mostly copy-paste constructs. \dokufootnote{Important: go step-by-step with easy testable parts}
\end{itemize}

\part{Index} 
\printindex 
%\section{Figures}
\listoffigures


\end{document}