reference.tex

来自「This a framework to test new ideas in tr」· TEX 代码 · 共 1,391 行 · 第 1/4 页

depending on whether the SUBS\_STATUS\_RESIZE\_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 \emph{SUBS\_MSG\_RESIZE}-message is sent to all ports that
changed size or the data-pointer.


\subsection{Subsytem-Flags}
\index{Subsystem!Flags}

These flags reflect the internal state of the susbsystem and are split in these
groups:
\begin{itemize}
\item{Propriety} reflect a general state of this subsystem which is more or less
static
\item{User-defined}, that is, set in the \_init-part of the module
\item{State} for transient information about the module
\end{itemize}


\subsubsection{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}
\item{SUBS\_STATUS\_THREAD} module has been threaded
\item{SUBS\_STATUS\_TRACKED} there is a stats\_track list with this module
\item{SUBS\_STATUS\_RESIZE\_DOWN} resize-messages go down
\item{SUBS\_STATUS\_RESIZE\_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.


\subsubsection{User-defined}

\index{Subsystem!Flags!SET\_STATUS}
\index{SET\_STATUS}
All these flags can be set in the \_init-part of the module by inserting a line
\begin{lyxcode}
SET\_STATUS( RESIZE\_NONE );
\end{lyxcode}
One has to note that with the SET\_STATUS-command the SUBS\_STATUS\_-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
\emph{SUBS\_STATUS\_RESIZE\_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\_data\_rcv need to be informed by changes on both the input and the
output. If this is the case, you have to set the
\emph{SUBS\_STATUS\_RESIZE\_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\_MSG\_PREPARE-message traverses all attached modules. Of course it has
to stop at the STFA, else every module will be in \emph{prepare}-status. If a
module has the \emph{SUBS\_STATUS\_PREPARE\_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
\emph{SUBS\_STATUS\_MULTI\_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\_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\_IN-flag set need to arrive
in chronological order. Taking the example of a MIMO\_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.

\subsubsection{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}
\item{SUBS\_STATUS\_RECONF} is set when the configuration-parameters have been
changed, but before the module's reconfig-method has been called.
\item{SUBS\_STATUS\_WORKING} indicates a module that is in it's pdata-method
\item{SUBS\_STATUS\_PREPARE} is a module that is 'locked' and ready to process
data.
\item{SUBS\_STATUS\_LISTED} in conjunction with the debug-interface, indicates
a module that is known to the visualize-tool
\end{itemize}


\subsection{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}
\item{Block-related} which define how the block is allocated and who takes care
about malloc/free
\item{Data-passing} which describe when a block of data is ready or when it
needs to change
\end{itemize}

\subsubsection{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}
\item{SWR\_PORT\_OWN\_MALLOC} this means that the module wants to keep track on
it's own about the different malloc/free
\item{SWR\_PORT\_OTHER\_FREE} another port is responsible for freeing this data
\item{SWR\_PORT\_OTHER\_MALLOC} another port is allocating the memory
\item{SWR\_PORT\_THIS\_FREE} this port is responsible for freeing the data
\item{SWR\_PORT\_PASSED\_THROUGH} this port passes the data through
\end{itemize}

\subsubsection{Signal-passing}

\index{Subsystem!Ports!SUBS\_PORT\_DATA}
The flag \emph{SUBS\_PORT\_DATA} is set whenever a module requests a buffer by
using \emph{buffer\_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 \emph{SUBS\_PORT\_GOT\_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|)}

\section{Module}

This section gives an overview of the module-creation and the use
of it. Even though \ref{cha:Extending-it} 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.


\subsection{General introduction}

Before a module can be used, it usually has to go through the following
steps:

\begin{enumerate}
\item Registration with the CDB, usually in \emph{module\_init}, this happens
when loading the module into memory 
\item Instantiation, which means setting up the needed memory and calling
\emph{init}
\item A call to \emph{reconfig} to assure that everything is OK 
\end{enumerate}
The points 2 and 3 are done automatically when calling \emph{swr\_sdb\_instantiate\_{*}}
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}
\item [pdata]Process an incoming data-block and eventually produce some
output-data 
\item [reconfig]Reconfigure itself because one of the configuration variables
have been changed 
\item [resize]Re-calculate its input- and output-sizes 
\item [custom-msg]React to a user-message 
\item [finalize]Clean up allocated values 
\end{lyxlist}
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 \emph{swr\_sdb\_set\_configure\_int}
you ask the MSR to set the configuration of this module-instance to
a certain value and to call the appropriate \emph{reconfig} function.


\subsection{\label{sub:Data-structures}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

\begin{lyxcode}
swr\_sdb\_get\_config\_struct(~context->id,~(void{*}{*})\&config~);~
\end{lyxcode}
before being able to use \emph{config-\textgreater{}something}. To
free the structure, use

\begin{lyxcode}
swr\_sdb\_free\_config\_struct(~context->id,~(void{*}{*})\&config~);~
\end{lyxcode}
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.


\subsection{\label{sub:Data-types}Data Types}


\subsubsection{For Config and Stats}


\paragraph{\label{par:Blocks}Blocks}

Blocks are a defined in the following way:

\begin{lyxcode}
typedef~struct~\{~~~

~~void~{*}data;~~~

~~int~size;~~~

~~swr\_signal\_type\_t~type;~

\}~block\_t;~
\end{lyxcode}
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 \emph{data} pointer has to point to the vectory you want to display,
\emph{size} is the size in units of \emph{type}, which is one of the
Data-Types described in here (w/o \emph{Block}, of course).


\paragraph{SYMBOL\_COMPLEX}

\begin{lyxcode}
typedef~struct~\{~~~

~~short~int~real;~~~

~~short~int~imag;~

\}~SYMBOL\_COMPLEX;~
\end{lyxcode}

\paragraph{SYMBOL\_COMPLEX\_S32}

\begin{lyxcode}
typedef~struct~\{~~~

~~int~real;~~~

~~int~imag;~

\}~SYMBOL\_COMPLEX;~
\end{lyxcode}

\paragraph{DOUBLE\_COMPLEX}

\begin{lyxcode}
typedef~struct~\{~~~

~~double~real;
  
~~double~imag;

\}~double\_complex;~
\end{lyxcode}

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

\paragraph{SYMBOL\_MMX}

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

\[
\begin{array}{cccc}
Re_{o} & Im_{0} & -Im_{0} & Re_{0}\end{array}\]


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:

\[
\begin{array}{cccc}
Re_{o} & Im_{0} & Re_{0} & Im_{0}\end{array}\]


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.


\paragraph{Simple Data-types}

\begin{lyxlist}{00.00.0000}
\item [U8]Unsigned 8-bit 
\item [S8]Signed 8-bit 
\item [U32]Unsigned 32-bit 
\item [S32]Signed 32-bit 
\item [SAMPLE\_S12]Signed 12-bit, where the 12 upper bits are used. For
the available hardware, the lower 4 bits signal RX/TX 
\item [SYMBOL\_S16]Signed 16-bit real symbol 
\item [DOUBLE] a double floating-point value
\end{lyxlist}

\subsection{\label{sub:Macros-to-use}Macros}

Each function that is defined in a module takes at least one argument:
\emph{swr\_sdb\_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 \emph{spc.h} which
is already included in the templates.