correct relative positionning of source/group

[blast.git] / doc / models-tg.tex

\documentclass[12pt,fleqn,a4paper]{article}
\usepackage[latin1]{inputenc}
%\usepackage[cyr]{aeguill}
\usepackage{xspace}
\usepackage{amsmath}
\usepackage{amsfonts}
\usepackage[english]{babel}
\usepackage{url}
\usepackage{multirow}
\let\urlorig\url
\renewcommand{\url}[1]{%
  \begin{otherlanguage}{english}\urlorig{#1}\end{otherlanguage}%
}

%\usepackage{pstricks,pst-node,pst-text,pst-3d}
\usepackage{graphicx}
\usepackage{thumbpdf}
\usepackage{color}
\usepackage{moreverb}
%\usepackage{commath}
\usepackage{subfigure}
%\input{psfig.sty}
\usepackage{fullpage}
\usepackage{fancybox}

\usepackage[ruled,lined,linesnumbered]{algorithm2e}

%%%%%%%%%%%%%%%%%%%%%%%%%%%% LyX specific LaTeX commands.
\newcommand{\noun}[1]{\textsc{#1}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%% my own LaTeX commands.
%\newcommand{\bibpath}[1]
%        {/home/sdomas/rapport/eigenjace/ipdps/#1}

\newcommand{\tab}{\ \ \ }
\newcommand{\ot}[1]{{\tt #1}}
%%%%%%%%%%%%%%%%%%%%%%%%%%%% my bib path.


\title{BLAST: classes and xml files for blocks (models, implementations and view)}

\author{St\'ephane Domas\\
Laboratoire d'Informatique
de l'Universit\'e de  Franche-Comt\'e, \\
BP 527, \\
90016~Belfort CEDEX, France\\}



\begin{document}

\maketitle

\thispagestyle{empty}
\section{What are blocks and items ?}
A block is the main unit to build a design in Blast. From the user
point of view, a block represents a process with inputs to consume
data, outputs to produce results. It may have some parameters
(e.g. the input/output data size). Thus, the user is not concerned
about how the block is really implemented in VHDL, just about the
"function" of the block. Some blocks are predefined, but the user can
also build them by composing predefined ones.

For the first type, the user has to choose the predefined blocks from
a library of "reference blocks" that do a particular processing
(i.e. a multiplication, a filter, ...), with default interface names
and parameter values. To add such a block to the design, a reference
block is cloned to obtain a "functional" block. It is similar to the
instanciation in object oriented programming: reference block
corresponds to the class, and functional block to the instance of that
class. Thus, a design may contain several functional blocks that
correspond to the same reference block. A reference block is
associated to one or several implementations that are in fact patterns
of VHDL code. One of them will be chosen more or less automatically by
Blast to produce the final VHDL code. The representation of an
implementation as a class and the structure of the files that contain
patterns are discussed in details in Section \ref{Implementations}.

The second type is named a "group" block. It is created empty or with
a set of existing functional blocks. For example, when a void design
is created, a group block is also created, that will represent the top
component in the VHDL code. User can add predefined blocks or even
other group blocks within a group very easily. There main purpose is
to make the design clearer and the VHDL more readable. Indeed, each
group will be translated into a VHDL component. Thus, instead of
having a single top component with a bunch of predefined blocks
within, they can be spread within groups to build a design
hierachically.

These three types of block are represented by a hierarchy of classes
that is described in details in Section \ref{sec:blocks_class}.\\

Reference, functional and group blocks are just containers of data,
i.e. they are part of the Model in MVC paradigm). The two latter have
a graphical counter part, named items, so that they can be represented
in the graphical interface. The hierarchy of classes
that represents the items is described in details in Section \ref{sec:items_class}.\\

\section{Class hierarchy for blocks}
\label{sec:blocks_class}

\subsection{the top class}
\label{sec:abstract_block_class}

The top class for describing block is {\tt AbstractBlock}, derived in
three subclasses: {\tt ReferenceBlock}, {\tt FunctionalBlock}, {\tt
  GroupBlock}.

Some attributes are common to every types, and defined in {\tt AbstractBlock}:
\begin{itemize}  
\item a name,
\item parameters,
\item input/output/bidirectional interfaces.
\end{itemize}

Parameters and interfaces are complex to represent and thus, are also
described by a hierarchy of classes in Section
\ref{sec:parameters_class} and \ref{sec:interfaces_class}.

\subsection{reference blocks}
\label{sec:reference_block_class}

A reference block is created taking informations in an XML file that
describes it, providing its parameters and interfaces. The structure
of that file is described in details in Section
\ref{sec:references_xml}.

A reference block also contains a list of {\tt
  BlockImplementation}. Each of them represents a pattern of VHDL code
that implements the function of the block.

\subsection{functional blocks}
\label{sec:functional_block_class}

A functional block has two attributes {\tt reference} and {\tt group}
that respectively refer to the reference block that has been cloned to
create that functional block, and the group block that contains it.


\subsection{group blocks}
\label{sec:group_block_class}

A group block has mainly two attributes {\tt parent} and {\tt
  blocks}. The first one is a pointer to the group that contains that
group (or {\tt NULL} if it is the top group). The second one is the
list of the functional or group blocks that are within this group.

{\bf Important: } a group block has no interface by itself. In fact,
they are created when the user wants to connect an interface of a
inner block to the outside of the block. Note that there is a 1:1
relation between a group interface and an interface of an inner
block. Nevertheless, an output group interface can still be connected
to several input interfaces.

{\bf Important: } a group block has no parameters by itself, except
if it contains blocks that may be configured via a wishbone. In this
case, the generic parameters to manage the wishbone are atuomaticcaly
added to the group.

\subsection{interfaces classes}
\label{sec:interfaces_class}

As for blocks, a top class {\tt AbstractInterface} represents the
common features of all interfaces and it is derived in three
subclasses: {\tt ReferenceInterface}, {\tt FunctionalInterface} and
{\tt GroupInterface}.

\subsection{parameters classes}
\label{sec:parameters_class}


There are four types of parameters for a block:
\begin{itemize}  
\item user,
\item generic,
\item port,
\item wishbone.  
\end{itemize}

These are represented by the top class {\tt BlockParameter} and four
subclasses: ({\tt BlockParameterUSer}, {\tt BlockParameterGeneric},
{\tt BlockParameterPort}, {\tt BlockParameterWishbone}.

Four attributes are common to all, and defined in {\tt BlockParameter}:
\begin{itemize}  
\item \ot{owner}: a pointer to the block instance (reference/functional) that ``owns'' this parameter,
\item \ot{name}: the name of the parameter (NB: cannot be changed by the user of BLAST),
\item \ot{type}: the type of the value,
\item \ot{value}: the default value of the parameter, given as a \ot{QString} but stored as a \ot{QVariant}.
\end{itemize}

\ot{type} value (int) must be set with one of those in \ot{ParamType} enum (cf. \ot{BlockParameter.h}):

\begin{verbatim}
enum ParamType { Undefined = -1, Expression = 1, Character, 
                 String, Bit, BitVector, Boolean, 
                 Integer, Natural, Positive, Real, Time};
\end{verbatim}
Except the two first, these values correspond to predefined types in
VHDL. \ot{Expression} correspond to an arithmetic expression and must
be used only for port and wishbone parameters. Thus, its syntax will
be presented in the associated sections (\ref{sec:parameters_port} and
\ref{parameters_wb}).\\

Whatever the case, parameters will be used during VHDL generation but at different phases, depending on the class.

\subsubsection{user parameters}
\label{sec:parameters_user}
User parameters have a type equals to \ot{String}. A default value
must be given at construction but a \ot{userValue} can be defined via
setters.\\

A user parameter is only used when generating the VHDL code of the
architecture section of a block (cf. section
\ref{sec:impls_xml}). Each time the generator encounters an escape
sequence: \ot{@val\{user\_parameter\_name\}}, it replaces it with
\ot{userValue} if defined, or with the default value.\\

{\bf CAUTION:} No validity check are done by BLAST on default and user
value strings. Thus, they can be anything and can lead to incorrect
VHDL.

\subsubsection{generic parameters}
\label{sec:parameters_generic}

Generic parameters have a type equals to any predefined VHDL type (i.e. all
defined above except \ot{Undefined} and \ot{Expression}). A default
value must be given at construction but a \ot{userValue} can be
defined via setters.\\

A generic parameter is used during the generation of:
\begin{itemize}
\item the entity section,
\item the component section when the owner block is used within another block,
\item the generic map of when instanciating owner block is used within another block,
\item the architecture section.
\end{itemize}

In the two first cases, it leads to lines like

\ot{d\_width : integer := 16;}, using the \ot{name}, \ot{type} and default value.

In the third case, it leads to lines like

\ot{d\_width => 10,}, using the \ot{name} and \ot{userValue},
or default value if not defined.

\ot{d\_width => d\_width,}, using only the
\ot{name}. This case occurs when the owner is instanciated within a
block that has a generic parameter with the same name.

In the last case, each time the generator encounters an escape
sequence: \ot{@val\{generic\_parameter\_name\}}, it replaces it with
\ot{userValue} if defined, or with the default value.\\

{\bf IMPORTANT:} a block that defines wishbone parameters will be
generated with 2 generic parameters with predefined names:
\ot{wb\_data\_width} and \ot{wb\_addr\_width}. They correspond to the
width of the address and data buses of the wishbone and are used
during the generation of the controller of the block
(cf. \ref{sec:parameters_wb}).

\subsubsection{port parameters}
\label{sec:parameters_port}
A port parameter can be used to obtain a value associated to an
interface of the block. Indeed, it is possible to create several
instances of the same interface, when its multiplicity given in the
reference model is greater than 1. For example, it is used for block
that may have a variable number of inputs/outputs, like a
multiplexer. Instead fo creating a bunch of multiplexers with 2, 3, 4,
$\ldots$ data inputs, it is possible to generate one for any
amount. In BLAST, this amount is given by the number of instances of
the data input the user has created. It implies that the selector
input has a variable range and thus needs a variable number of bits to
be expressed. If $N$ is the number of instances of the data input,
then the selector size is $log_2(N)$. A port parameter is used to
express such a value.\\

A port parameters have a supplementary attribute \ot{ifaceName} that
must correspond to an existing interface of the block. \ot{type} is
equal to \ot{Expression} and \ot{value} contains this expression,
using variables with a predefined name \ot{\$if\_nb} and
\ot{\$if\_width} that will be respectively replace during VHDL
generation by the number of instances of \ot{ifaceName}, and its
width.

A port parameter is used during the generation of:
\begin{itemize}
\item the entity section,
\item the component section when the owner block is used within another block,
\item the architecture section.
\end{itemize}

In every case, each time the generator encounters an escape sequence:
\ot{@val\{port\_parameter\_name\}}, it replaces it with the computed
value of the parameter using the expression and the interface name.


\subsubsection{wishbone parameters}
\label{sec:parameters_wb}

A wishbone parameter corresponds to a register that can be read/write
via the wishbone bus. Nevertheless, the GUI allows the user to disable
the wishbone access and replace it by a fixed value or a port that is
assign to the register.

Since a register has a width, \ot{type} gives its type. Valid types are:
\begin{itemize}
\item \ot{boolean} if the register is an \ot{std\_logic},
\item \ot{natural} if the register has a fixed width and is a \ot{std\_logic\_vector},
\item \ot{expression} if the register has a variable width and is a \ot{std\_logic\_vector},  
\end{itemize}
The width is given in a supplementary attribute \ot{width}. Note that:
\begin{itemize}
\item if the type is boolean, width should be equal to 1 but in fact is not used.

\item if the type is natural and width is equal to 1, it leads to
\ot{std\_logic\_vector(0 downto 0)}, which is sometimes usefull for
memory accesses.

\item if the type is an expression, width must contains an expression
  using only +,-,*, numbers and generic parameter references
  (i.e. parameter name prepend with a $). No check is done thus, the
  model must be correct so that valid VHDL will be produced.
\end{itemize}

In the second case, the expression may use predefined names
\ot{wb\_data\_width} and \ot{wb\_addr\_width}.

Whatever the case, during VHDL generation, the final width will be
compared to the wishbone data bus width. If the bus width is lesser
than the register width, then several wishbone accesses are needed to
read/write the register. For example, if wishbone width is 16 and a
register has a width of 20, we need to define two addresses, one to
access to bits 0 to 15, and one for bits 16 to 19. The total number of
needed addresses gives the minimal width of the address bus (i.e. log2(nb addr)).\\

The value is a initialization value. If not provided, it is 0 by
default.\\

Three other attributes are declared:
\begin{itemize}
\item \ot{wbAccess}: indicates if the register is written or read by
  the wishbone bus. Thus, if it is written, the register is an input
  of the block and if it is read, the block provides its value.
\item \ot{wbValue}: it may be a natural, a boolean, or the word
  data. In the two first cases, the given value is affected to the
  register as soon as the register is accessed in writing. In the
  third case, the register is affected with the value that is provided
  on the wishbone data bus.
\item \ot{wbDuration} : indicates if the affectation is permanent or
  just a trigger. In the second case, the value is set for just one
  clock cycle and then reset to the initialization value given by the
  \ot{value} attribute.\\
\end{itemize}

A wishbone parameter is used during the generation of:
\begin{itemize}
\item the controller of the block (NB: this generation is done at the block level),
\item the entity section, because register values are in fact read/write by the block via input/output ports,
\item the component section when the owner block is used within another block.
\end{itemize}

\section{Implementations XML description}
\label{sec:impls_xml}

\section{Implementations class hierarchy}
\label{sec:impls_class}


\end{document}