Skip to content

H
HDL Core Lib
Commit dee54890 authored by Tomasz Wlostowski's avatar Tomasz Wlostowski
Browse files
Options

docs uploaded

parent 9d19b097
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 9214 additions and 0 deletions
trunk/software/wbgen2/doc-src/intro.aux 0 → 100644
View file @ dee54890
\relax
\@writefile{toc}{\contentsline {section}{\numberline {1}Introduction}{2}{section.1}}
\@writefile{lof}{\contentsline {figure}{\numberline {1}{\ignorespaces An example of wbgen2-generated slave core}}{2}{figure.1}}
\newlabel{fig:slavecore}{{1}{2}{An example of wbgen2-generated slave core\relax }{figure.1}{}}
\@setckpt{intro}{
\setcounter{page}{3}
\setcounter{equation}{0}
\setcounter{enumi}{0}
\setcounter{enumii}{0}
\setcounter{enumiii}{0}
\setcounter{enumiv}{0}
\setcounter{footnote}{0}
\setcounter{mpfootnote}{0}
\setcounter{part}{0}
\setcounter{section}{1}
\setcounter{subsection}{0}
\setcounter{subsubsection}{0}
\setcounter{paragraph}{0}
\setcounter{subparagraph}{0}
\setcounter{figure}{1}
\setcounter{table}{0}
\setcounter{Item}{0}
\setcounter{Hfootnote}{0}
\setcounter{bookmark@seq@number}{0}
\setcounter{lstnumber}{1}
\setcounter{LT@tables}{0}
\setcounter{LT@chunks}{0}
\setcounter{subfigure}{0}
\setcounter{lofdepth}{1}
\setcounter{subtable}{0}
\setcounter{lotdepth}{1}
\setcounter{section@level}{1}
\setcounter{lstlisting}{0}
}
trunk/software/wbgen2/doc-src/intro.log 0 → 100644
View file @ dee54890
This diff is collapsed.
trunk/software/wbgen2/doc-src/intro.tex 0 → 100644
View file @ dee54890
\section{Introduction}
\textbf{wbgen2} is a Lua script for generating VHDL Wishbone slave cores from a register set description provided by the user. By the ''slave core'' we mean a HDL entity which is connected to Wishbone bus on one side, and on the other side it provides ports for accessing memory mapped registers, FIFOs and RAMs, as shown on figure \ref{fig:slavecore}.
\InsertDefFig{slavecore.pdf}{An example of wbgen2-generated slave core}{fig:slavecore}{1}
The main features of wbgen2 are listed below:
\begin{itemize}
\item Generation of VHDL code for slaves consisting of memory mapped registers, FIFO registers and RAMs
\item Automatic minimal address space generation
\item Generation of C header files containing addresses consistent with the VHDL core
\item Customizable register types, with multiple access options and multiple clocking schemes
\item Support for most common VHDL types
\item (optional) automatic instantiation and wiring of slave core into the VHDL design
\item (optional) documentation generator.
\end{itemize}
trunk/software/wbgen2/doc-src/main.aux 0 → 100644
View file @ dee54890
\relax
\providecommand\BKM@entry[2]{}
\ifx\hyper@anchor\@undefined
\global \let \oldcontentsline\contentsline
\gdef \contentsline#1#2#3#4{\oldcontentsline{#1}{#2}{#3}}
\global \let \oldnewlabel\newlabel
\gdef \newlabel#1#2{\newlabelxx{#1}#2}
\gdef \newlabelxx#1#2#3#4#5#6{\oldnewlabel{#1}{{#2}{#3}}}
\AtEndDocument{\let \contentsline\oldcontentsline
\let \newlabel\oldnewlabel}
\else
\global \let \hyper@last\relax
\fi
\@input{title.aux}
\select@language{english}
\@writefile{toc}{\select@language{english}}
\@writefile{lof}{\select@language{english}}
\@writefile{lot}{\select@language{english}}
\select@language{english}
\@writefile{toc}{\select@language{english}}
\@writefile{lof}{\select@language{english}}
\@writefile{lot}{\select@language{english}}
\@input{intro.aux}
\BKM@entry{id=1,dest={73656374696F6E2E31}}{496E74726F64756374696F6E}
\@input{processing.aux}
\BKM@entry{id=2,dest={73656374696F6E2E32}}{776267656E3220736C617665206465736372697074696F6E2066696C6573}
\BKM@entry{id=3,dest={73756273656374696F6E2E322E31}}{536C617665206465736372697074696F6E2073796E746178}
\BKM@entry{id=4,dest={73756273656374696F6E2E322E32}}{436F6D6D6F6E2061747472696275746573}
\BKM@entry{id=5,dest={73756273656374696F6E2E322E33}}{5045524950484552414C20626C6F636B2061747472696275746573}
\BKM@entry{id=6,dest={73756273656374696F6E2E322E34}}{52454720626C6F636B2061747472696275746573}
\BKM@entry{id=7,dest={73756273656374696F6E2E322E35}}{4649454C4420626C6F636B}
\@input{regs.aux}
\BKM@entry{id=8,dest={73656374696F6E2E33}}{526567697374657273}
trunk/software/wbgen2/doc-src/main.log 0 → 100644
View file @ dee54890
This diff is collapsed.
trunk/software/wbgen2/doc-src/main.out.ps 0 → 100644
View file @ dee54890
%!
/pdfmark where{pop}
{/globaldict where{pop globaldict}{userdict}ifelse/pdfmark/cleartomark load put}
ifelse
trunk/software/wbgen2/doc-src/main.tex 0 → 100755
View file @ dee54890
\documentclass[a4paper,11pt]{article}
\usepackage{lmodern}
\usepackage{t1enc}
\usepackage[pdftex]{hyperref}
\usepackage{listings}
\usepackage[pdftex]{color,graphicx}
\usepackage{bookmark}
\usepackage[english]{babel}
\usepackage[utf8]{inputenc}
\usepackage{relsize}
\usepackage{setspace}
\usepackage{xstring}
%\usepackage{tabularx}
\usepackage{ltablex}
%\usepackage{fancyhdr}
\usepackage{subfigure}
\usepackage{textcomp}
\usepackage{multirow}
\usepackage{fullpage}
%\pagestyle{fancy}
\widowpenalty=10000
\clubpenalty=10000
\brokenpenalty=10000
\sloppy
\lstset{
language=C++, % choose the language of the code
basicstyle=\tiny, % the size of the fonts that are used for the code
numbers=none, % where to put the line-numbers
%numberstyle=\footnotesize, % the size of the fonts that are used for the line-numbers
%stepnumber=1, % the step between two line-numbers
%numbersep=5pt, % how far the line-numbers are from the code
backgroundcolor=\color{white}, % choose the background color. You must add \usepackage{color}
showspaces=false, % show spaces adding particular underscores
showstringspaces=true, % underline spaces within strings
showtabs=false, % show tabs within strings adding particular underscores
frame=tlBR, % adds a frame around the code
frameround=tttt, % a moze trBL / tttt
tabsize=2, % sets default tabsize to 2 spaces
captionpos=t, % sets the caption-position to top
breaklines=true, % sets automatic line breaking
breakatwhitespace=true, % sets if automatic breaks should only happen at whitespace
breakindent=100px,
prebreak=\ldots, % 1,
morekeywords={uint8_t,int32_t,int64_t,uint32_t,uint64_t},
%escapeinside={\%*}{*)} % if you want to add a comment within your code
lineskip=0pt,
inputencoding=utf8,
}
\newcommand{\HRule}{\rule{\linewidth}{0.3mm}}
\newcommand{\DocumentVersion}{20100223}
\def\us{\char`\_}
\newcommand{\InsertDefFig}[4]{
\begin{figure}[h]
\centering
\includegraphics[width=#4\textwidth]{#1}
\caption{#2}
\label{#3}
\end{figure}
}
\begin{document}
\selectlanguage{english}
\author{Tomasz Włostowski}
\title{wbgen2 documentation}
\include{title}
\include{intro}
\include{processing}
\include{regs}
\end{document}
trunk/software/wbgen2/doc-src/main.tex~ 0 → 100755
View file @ dee54890
\documentclass[a4paper,11pt]{article}
\usepackage{lmodern}
\usepackage{t1enc}
\usepackage[pdftex]{hyperref}
\usepackage{listings}
\usepackage[pdftex]{color,graphicx}
\usepackage{bookmark}
\usepackage[english]{babel}
\usepackage[utf8]{inputenc}
\usepackage{relsize}
\usepackage{setspace}
\usepackage{xstring}
%\usepackage{tabularx}
\usepackage{ltablex}
%\usepackage{fancyhdr}
\usepackage{subfigure}
\usepackage{textcomp}
\usepackage{multirow}
\usepackage{fullpage}
%\pagestyle{fancy}
\widowpenalty=10000
\clubpenalty=10000
\brokenpenalty=10000
\sloppy
\lstset{
language=C++, % choose the language of the code
basicstyle=\tiny, % the size of the fonts that are used for the code
numbers=none, % where to put the line-numbers
%numberstyle=\footnotesize, % the size of the fonts that are used for the line-numbers
%stepnumber=1, % the step between two line-numbers
%numbersep=5pt, % how far the line-numbers are from the code
backgroundcolor=\color{white}, % choose the background color. You must add \usepackage{color}
showspaces=false, % show spaces adding particular underscores
showstringspaces=true, % underline spaces within strings
showtabs=false, % show tabs within strings adding particular underscores
frame=tlBR, % adds a frame around the code
frameround=tttt, % a moze trBL / tttt
tabsize=2, % sets default tabsize to 2 spaces
captionpos=t, % sets the caption-position to top
breaklines=true, % sets automatic line breaking
breakatwhitespace=true, % sets if automatic breaks should only happen at whitespace
breakindent=100px,
prebreak=\ldots, % 1,
morekeywords={uint8_t,int32_t,int64_t,uint32_t,uint64_t},
%escapeinside={\%*}{*)} % if you want to add a comment within your code
lineskip=0pt,
inputencoding=utf8,
}
\newcommand{\HRule}{\rule{\linewidth}{0.3mm}}
\newcommand{\DocumentVersion}{20100223}
\def\us{\char`\_}
\newcommand{\InsertDefFig}[4]{
\begin{figure}[h]
\centering
\includegraphics[width=#4\textwidth]{#1}
\caption{#2}
\label{#3}
\end{figure}
}
\begin{document}
\selectlanguage{english}
\author{Tomasz Włostowski}
\title{wbgen2 documentation}
\include{title}
\include{intro}
\include{processing}
\end{document}
trunk/software/wbgen2/doc-src/processing.aux 0 → 100644
View file @ dee54890
\relax
\@writefile{toc}{\contentsline {section}{\numberline {2}wbgen2 slave description files}{3}{section.2}}
\@writefile{lof}{\contentsline {figure}{\numberline {2}{\ignorespaces Structure of slave cores generated by wbgen2}}{3}{figure.2}}
\newlabel{fig:reglayout}{{2}{3}{Structure of slave cores generated by wbgen2\relax }{figure.2}{}}
\@writefile{toc}{\contentsline {subsection}{\numberline {2.1}Slave description syntax}{3}{subsection.2.1}}
\gdef \LT@i {\LT@entry
{1}{98.15825pt}\LT@entry
{1}{354.80965pt}}
\gdef \LT@ii {\LT@entry
{1}{98.15825pt}\LT@entry
{1}{298.13481pt}}
\gdef \LT@iii {\LT@entry
{1}{98.15825pt}\LT@entry
{1}{354.80965pt}}
\gdef \LT@iv {\LT@entry
{1}{105.342pt}\LT@entry
{1}{278.1937pt}}
\@writefile{toc}{\contentsline {subsection}{\numberline {2.2}Common attributes}{4}{subsection.2.2}}
\@writefile{lot}{\contentsline {table}{\numberline {1}{Attributes common for all description blocks}}{4}{table.1}}
\@writefile{toc}{\contentsline {subsection}{\numberline {2.3}PERIPHERAL block attributes}{4}{subsection.2.3}}
\@writefile{lot}{\contentsline {table}{\numberline {2}{Attributes specific for \textbf {peripheral} blocks}}{4}{table.2}}
\@writefile{toc}{\contentsline {subsection}{\numberline {2.4}REG block attributes}{4}{subsection.2.4}}
\@writefile{lot}{\contentsline {table}{\numberline {3}{Attributes specific for \textbf {reg} blocks}}{4}{table.3}}
\gdef \LT@v {\LT@entry
{1}{126.61101pt}\LT@entry
{1}{326.35689pt}}
\@writefile{lot}{\contentsline {table}{\numberline {4}{Possible field types for \textbf {reg} blocks}}{5}{table.4}}
\newlabel{table:fieldtypes}{{4}{5}{Possible field types for \textbf {reg} blocks\relax }{table.4}{}}
\@writefile{lof}{\contentsline {figure}{\numberline {3}{\ignorespaces Register alignment}}{5}{figure.3}}
\newlabel{fig:regalignment}{{3}{5}{Register alignment\relax }{figure.3}{}}
\@writefile{toc}{\contentsline {subsection}{\numberline {2.5}FIELD block}{5}{subsection.2.5}}
\@writefile{lot}{\contentsline {table}{\numberline {5}{Attributes specific for \textbf {field} blocks}}{6}{table.5}}
\@setckpt{processing}{
\setcounter{page}{7}
\setcounter{equation}{0}
\setcounter{enumi}{0}
\setcounter{enumii}{0}
\setcounter{enumiii}{0}
\setcounter{enumiv}{0}
\setcounter{footnote}{0}
\setcounter{mpfootnote}{0}
\setcounter{part}{0}
\setcounter{section}{2}
\setcounter{subsection}{5}
\setcounter{subsubsection}{0}
\setcounter{paragraph}{0}
\setcounter{subparagraph}{0}
\setcounter{figure}{3}
\setcounter{table}{5}
\setcounter{Item}{0}
\setcounter{Hfootnote}{0}
\setcounter{bookmark@seq@number}{0}
\setcounter{lstnumber}{29}
\setcounter{LT@tables}{5}
\setcounter{LT@chunks}{1}
\setcounter{subfigure}{0}
\setcounter{lofdepth}{1}
\setcounter{subtable}{0}
\setcounter{lotdepth}{1}
\setcounter{section@level}{2}
\setcounter{lstlisting}{0}
}
trunk/software/wbgen2/doc-src/processing.log 0 → 100644
View file @ dee54890
This diff is collapsed.
trunk/software/wbgen2/doc-src/processing.tex 0 → 100644
View file @ dee54890
\section{wbgen2 slave description files}
In order to generate the slave core, user must provide a slave description file, which tells wbgen2 what he wants to have inside the core. Each slave description file contains a tree-like structure, describing the peripheral's register layout for a single Wishbone peripheral.
Slaves may contain registers, FIFO registers and RAM memories. Registers and FIFO registers consist of fields (see figure \ref{fig:reglayout}), RAMs are accessible as plain, synchronous memories.
\InsertDefFig{reglayout.pdf}{Structure of slave cores generated by wbgen2}{fig:reglayout}{0.8}
\subsection{Slave description syntax}
Slave description files have C-like syntax. Each file may contain the description of a single slave core. The description must begin with \textit{peripheral} block, which contains one or more of
\textit{reg}, \textit{fiforeg} or \textit{ram} subblocks. Each \textit{reg} and \textit{fiforeg} subblock must contain at least one \textit{field}. Inside each block, there is a list of attributes. The listing below shows a dummy description file layout:
\begin{lstlisting}
peripheral {
name = "My peripheral";
c_prefix = "periph1";
hdl_prefix = "periph1";
reg {
name = "My register";
prefix = "myreg";
description = "A longer description";
field {
name = "My field 1";
prefix = "field1";
type = type-of-the-field; // BIT, SLV, etc...
};
-- more fields here...
};
fiforeg {
name = "My FIFO register";
prefix = "myram";
field { ... };
};
ram {
name = "My RAM";
prefix = "myram";
size = 1024;
};
};
\end{lstlisting}
\subsection{Common attributes}
There are few attributes, which are common for all types of blocks in the description file:
%\begin{table}[h]
\begin{tabularx}{\textwidth}{|p{3cm}|X|}
\hline
\textbf{name}
\newline
(mandatory)
& contains a short (single line) human-readable name for the peripheral/register/field. This name is not used directly in code generation (except for the code comments).
\\\hline
\textbf{c\us prefix}\newline
\textbf{hdl\us prefix}\newline
\textbf{prefix}\newline
(mandatory)
& contains a short prefix for each block which is used for generation of VHDL port/signal names and C macros. Names are generated by concatenating the prefixes. In the example shown above, the signal name of field "My field 1" would be \textit{periph1\us myreg\us field1}. The format of \textbf{prefix} value must follow the language syntax rules and your coding style. Note that you can provide either separate prefixes for C/HDL languages (\textbf{c\us prefix, hdl\us prefix}) or a single \textbf{prefix} for both.
\\\hline
\textbf{description}\newline
(optional)
& a longer description of the block, used by the documentation generator.
\\\hline
\caption{Attributes common for all description blocks}
\end{tabularx}
%\end{table}
\subsection{PERIPHERAL block attributes}
\textbf{Peripheral} block is the top-level block in the description file.
\newline
Block-specific attributes:
%\begin{table}[h]
\begin{tabularx}{\textwidth}{|p{3cm}|X|}
\hline
\textbf{hdl\us entity}
\newline
(mandatory)
& name of the VHDL entity of the slave core to be generated.
\\\hline
\caption{Attributes specific for \textbf{peripheral} blocks}
\end{tabularx}
%\end{table}
\subsection{REG block attributes}
\textbf{Reg} block describes a single memory-mapped register. Each \textbf{reg} block must contain one or more
\textbf{field} blocks. Available field types are listed in table \ref{table:fieldtypes}.
\newline Block-specific attributes:
%\begin{table}[h]
\begin{tabularx}{\textwidth}{|p{3cm}|X|}
\hline
\textbf{align = val}
\newline
(optional)
& Alignment value for the field address. When given, wbgen2 will align the address of this register to the nearest multiple of \textit{val}. See also figure \ref{fig:regalignment}.
\\\hline
\caption{Attributes specific for \textbf{reg} blocks}
\end{tabularx}
%\end{table}
%\begin{table}[h]
\begin{tabularx}{\textwidth}{|l|X|}
\hline
\textbf{Type} & \textbf{Description}
\\\hline
BIT & VHDL single bit of type \texttt{std\us logic} \\
SLV & VHDL field of type \texttt{std\us logic\us vector} \\
SIGNED & VHDL field of type \texttt{signed} \\
UNSIGNED & VHDL field of type \texttt{unsigned} \\
MONOSTABLE & VHDL field of type \texttt{std\us logic}, generating a single-cycle positive pulse upon bus write of '1'. \\
PASS\us THROUGH & special field, for which wbgen2 will generate only the address decoding logic which provides "wr" signal asserted high for a single WB clock cycle upon each write to the register. The written value will be fed to the corresponding SLV output directly from the Wishbone bus (just wires, no registers in between).
\\\hline
\caption{Possible field types for \textbf{reg} blocks}
\label{table:fieldtypes}
\end{tabularx}
%\end{table}
\InsertDefFig{alignment.pdf}{Register alignment}{fig:regalignment}{0.4}
\subsection{FIELD block}
\textbf{Field} block describes a single register field. There are several types of fields, shown in table \ref{table:fieldtypes}. It's the most elementary block in the design.
\newline
Block-specific attributes:
%\begin{table}[]
\begin{tabularx}{\textwidth}{|p{4cm}|X|}
\hline
\textbf{type}\newline (mandatory)
& type of the field. See table \ref {table:fieldtypes} \\\hline
\textbf{size}\newline (mandatory for: SLV, optional for SIGNED, UNSIGNED)
& size of the field in bits. For SIGNED and UNSIGNED types it's interchangeable with \textbf {range} attribute.\\\hline
\textbf{range = \{min,max\}}\newline (optional for SIGNED, UNSIGNED)
& minimal and maximal field value. When provided, wbgen2 will automatically calculate the necessary number of bits. \\\hline
\textbf{access\us bus}\newline
\textbf{access\us dev}\newline
(optional)
& field access flags. \textbf{access\us bus} defines how the field can be accessed from the Wishbone bus, \textbf{access\us dev} defines how the field can be modified by the HDL entity in which the slave core is instantiated. Access flags can have one of these values: READ\us ONLY, WRITE\us ONLY, READ\us WRITE. For the possible access combinations refer to table \ref{table:accessflags}. \newline
The default value is READ\us WRITE (from the bus) and READ\us ONLY (from the device).
\\\hline
\textbf{access}\newline
(optional)
& can be used instead of \textbf{access\us bus} and \textbf{access\us dev} to define access rights. See table \ref{table:accessflags}.
\\\hline
\textbf{align = num}\newline
(optional)
& when given, the bit offset at which field will be allocated, will be aligned to integer multiple of \textbf{num}. Default value is 1 (no alignment).
\\\hline
\textbf{clock}\newline
(optional)
& can be used to provide a clock port name if the field needs to operate in clock domain other than Wishbone bus clock. wbgen2 will automatically provide the necessary synchronization logic. Clock names are automatically appended to slave core entity port list. If no \textbf{clock} attribute is provided, wbgen2 defaults to Wishbone bus clock.
\\\hline
\textbf{load}\newline
(optional for RW/RW fields)
& this attribute is applicable only to RW/RW-accessed fields (e.g. the fields which are writable both from the bus and the device). There are two possible values, indicating where the field register will be physically placed (see figure \ref{fig:loadintext}):
\newline
\textit{LOAD\us EXT} - the field register is placed outside the slave core. Upon bus write operation, slave outputs the new value to the output port and asserts the "load" signal for a single clock cycle. The device has to handle these signals and update the value of the register respectively.
\newline
\textit{LOAD\us INT} - the field register is placed inside the slave core. When the device wants to update it's value, it passes it to certain input port and asserts the load signal high. \textit{not implemented yet}.
\\\hline
\caption{Attributes specific for \textbf{field} blocks}
\end{tabularx}
%\end{table}
trunk/software/wbgen2/doc-src/processing.tex.backup 0 → 100644
View file @ dee54890
\section{wbgen2 slave description files}
In order to generate the slave core, user must provide a slave description file, which tells wbgen2 what he wants to have inside the core. Each slave description file contains a tree-like structure, describing the peripheral's register layout for a single Wishbone peripheral.
Slaves may contain registers, FIFO registers and RAM memories. Registers and FIFO registers consist of fields (see figure \ref{fig:reglayout}), RAMs are accessible as plain, synchronous memories.
\InsertDefFig{reglayout.pdf}{Structure of slave cores generated by wbgen2}{fig:reglayout}{0.8}
\subsection{Slave description syntax}
Slave description files have C-like syntax. Each file may contain the description of a single slave core. The description must begin with \textit{peripheral} block, which contains one or more of
\textit{reg}, \textit{fiforeg} or \textit{ram} subblocks. Each \textit{reg} and \textit{fiforeg} subblock must contain at least one \textit{field}. Inside each block, there is a list of attributes. The listing below shows a dummy description file layout:
\begin{lstlisting}
peripheral {
name = "My peripheral";
c_prefix = "periph1";
hdl_prefix = "periph1";
reg {
name = "My register";
prefix = "myreg";
description = "A longer description";
field {
name = "My field 1";
prefix = "field1";
type = type-of-the-field; // BIT, SLV, etc...
};
-- more fields here...
};
fiforeg {
name = "My FIFO register";
prefix = "myram";
field { ... };
};
ram {
name = "My RAM";
prefix = "myram";
size = 1024;
};
};
\end{lstlisting}
\subsection{Common attributes}
There are few attributes, which are common for all types of blocks in the description file:
\begin{table}[h]
\begin{tabularx}{\textwidth}{|p{3cm}|X|}
\hline
\textbf{name}
\newline
(mandatory)
& contains a short (single line) human-readable name for the peripheral/register/field. This name is not used directly in code generation (except for the code comments).
\\\hline
\textbf{c\us prefix}\newline
\textbf{hdl\us prefix}\newline
\textbf{prefix}\newline
(mandatory)
& contains a short prefix for each block which is used for generation of VHDL port/signal names and C macros. Names are generated by concatenating the prefixes. In the example shown above, the signal name of field "My field 1" would be \textit{periph1\us myreg\us field1}. The format of \textbf{prefix} value must follow the language syntax rules and your coding style. Note that you can provide either separate prefixes for C/HDL languages (\textbf{c\us prefix, hdl\us prefix}) or a single \textbf{prefix} for both.
\\\hline
\textbf{description}\newline
(optional)
& a longer description of the block, used by the documentation generator.
\\\hline
\end{tabularx}
\end{table}
\subsection{PERIPHERAL block attributes}
\textbf{Peripheral} block is the top-level block in the description file.
\newline
Block-specific attributes:
\begin{table}[h]
\begin{tabularx}{\textwidth}{|p{3cm}|X|}
\hline
\textbf{hdl\us entity}
\newline
(mandatory)
& name of the VHDL entity of the slave core to be generated.
\\\hline
\end{tabularx}
\end{table}
\subsection{REG block attributes}
\textbf{Reg} block describes a single memory-mapped register. Each \textbf{reg} block must contain one or more
\textbf{field} blocks. Available field types are listed in table \ref{table:fieldtypes}.
\newline Block-specific attributes:
\begin{table}[h]
\begin{tabularx}{\textwidth}{|p{3cm}|X|}
\hline
\textbf{align = val}
\newline
(optional)
& Alignment value for the field address. When given, wbgen2 will align the address of this register to the nearest multiple of \textit{val}. See also figure \ref{fig:regalignment}.
\\\hline
\end{tabularx}
\end{table}
\begin{table}[h]
\begin{tabularx}{\textwidth}{|l|X|}
\hline
\textbf{Type} & \textbf{Description}
\\\hline
BIT & VHDL single bit of type \texttt{std\us logic} \\
SLV & VHDL field of type \texttt{std\us logic\us vector} \\
SIGNED & VHDL field of type \texttt{signed} \\
UNSIGNED & VHDL field of type \texttt{unsigned} \\
MONOSTABLE & VHDL field of type \texttt{std\us logic}, generating a single-cycle positive pulse upon bus write of '1'. \\
PASS\us THROUGH & special field, for which wbgen2 will generate only the address decoding logic which provides "wr" signal asserted high for a single WB clock cycle upon each write to the register. The written value will be fed to the corresponding SLV output directly from the Wishbone bus (just wires, no registers in between).
\\\hline
\end{tabularx}
\label{table:fieldtypes}
\caption{Possible field types for \textbf{reg} blocks}
\end{table}
\InsertDefFig{alignment.pdf}{Register alignment}{fig:regalignment}{0.4}
\subsection{FIELD block}
\textbf{Field} block describes a single register field. There are several types of fields, shown in table \ref{table:fieldtypes}. It's the most elementary block in the design.
\newline
Block-specific attributes:
\begin{table}[]
\begin{tabularx}{\textwidth}{|p{4cm}|X|}
\hline
\textbf{type}\newline (mandatory)
& type of the field. See table \ref {table:fieldtypes} \\\hline
\textbf{size}\newline (mandatory for: SLV, optional for SIGNED, UNSIGNED)
& size of the field in bits. For SIGNED and UNSIGNED types it's interchangeable with \textbf {range} attribute.\\\hline
\textbf{range = \{min,max\}}\newline (optional for SIGNED, UNSIGNED)
& minimal and maximal field value. When provided, wbgen2 will automatically calculate the necessary number of bits. \\\hline
\textbf{access\us bus}\newline
\textbf{access\us dev}\newline
(optional)
& field access flags. \textbf{access\us bus} defines how the field can be accessed from the Wishbone bus, \textbf{access\us dev} defines how the field can be modified by the HDL entity in which the slave core is instantiated. Access flags can have one of these values: READ\us ONLY, WRITE\us ONLY, READ\us WRITE. For the possible access combinations refer to table \ref{table:accessflags}. \newline
The default value is READ\us WRITE (from the bus) and READ\us ONLY (from the device).
\\\hline
\textbf{access}\newline
(optional)
& can be used instead of \textbf{access\us bus} and \textbf{access\us dev} to define access rights. See table \ref{table:accessflags}.
\\\hline
\textbf{align = num}\newline
(optional)
& when given, the bit offset at which field will be allocated, will be aligned to integer multiple of \textbf{num}. Default value is 1 (no alignment).
\\\hline
\textbf{clock}\newline
(optional)
& can be used to provide a clock port name if the field needs to operate in clock domain other than Wishbone bus clock. wbgen2 will automatically provide the necessary synchronization logic. Clock names are automatically appended to slave core entity port list. If no \textbf{clock} attribute is provided, wbgen2 defaults to Wishbone bus clock.
\\\hline
\textbf{load}\newline
(optional for RW/RW fields)
& this attribute is applicable only to RW/RW-accessed fields (e.g. the fields which are writable both from the bus and the device). There are two possible values, indicating where the field register will be physically placed (see figure \ref{fig:loadintext}):
\newline
\textit{LOAD\us EXT} - the field register is placed outside the slave core. Upon bus write operation, slave outputs the new value to the output port and asserts the "load" signal for a single clock cycle. The device has to handle these signals and update the value of the register respectively.
\newline
\textit{LOAD\us INT} - the field register is placed inside the slave core. When the device wants to update it's value, it passes it to certain input port and asserts the load signal high. \textit{not implemented yet}.
\\\hline
\end{tabularx}
\end{table}
trunk/software/wbgen2/doc-src/processing.tex~ 0 → 100644
View file @ dee54890
\section{wbgen2 slave description files}
In order to generate the slave core, user must provide a slave description file, which tells wbgen2 what he wants to have inside the core. Each slave description file contains a tree-like structure, describing the peripheral's register layout for a single Wishbone peripheral.
Slaves may contain registers, FIFO registers and RAM memories. Registers and FIFO registers consist of fields (see figure \ref{fig:reglayout}), RAMs are accessible as plain, synchronous memories.
\InsertDefFig{reglayout.pdf}{Structure of slave cores generated by wbgen2}{fig:reglayout}{0.8}
\subsection{Slave description syntax}
Slave description files have C-like syntax. Each file may contain the description of a single slave core. The description must begin with \textit{peripheral} block, which contains one or more of
\textit{reg}, \textit{fiforeg} or \textit{ram} subblocks. Each \textit{reg} and \textit{fiforeg} subblock must contain at least one \textit{field}. Inside each block, there is a list of attributes. The listing below shows a dummy description file layout:
\begin{lstlisting}
peripheral {
name = "My peripheral";
c_prefix = "periph1";
hdl_prefix = "periph1";
reg {
name = "My register";
prefix = "myreg";
description = "A longer description";
field {
name = "My field 1";
prefix = "field1";
type = type-of-the-field; // BIT, SLV, etc...
};
-- more fields here...
};
fiforeg {
name = "My FIFO register";
prefix = "myram";
field { ... };
};
ram {
name = "My RAM";
prefix = "myram";
size = 1024;
};
};
\end{lstlisting}
\subsection{Common attributes}
There are few attributes, which are common for all types of blocks in the description file:
%\begin{table}[h]
\begin{tabularx}{\textwidth}{|p{3cm}|X|}
\hline
\textbf{name}
\newline
(mandatory)
& contains a short (single line) human-readable name for the peripheral/register/field. This name is not used directly in code generation (except for the code comments).
\\\hline
\textbf{c\us prefix}\newline
\textbf{hdl\us prefix}\newline
\textbf{prefix}\newline
(mandatory)
& contains a short prefix for each block which is used for generation of VHDL port/signal names and C macros. Names are generated by concatenating the prefixes. In the example shown above, the signal name of field "My field 1" would be \textit{periph1\us myreg\us field1}. The format of \textbf{prefix} value must follow the language syntax rules and your coding style. Note that you can provide either separate prefixes for C/HDL languages (\textbf{c\us prefix, hdl\us prefix}) or a single \textbf{prefix} for both.
\\\hline
\textbf{description}\newline
(optional)
& a longer description of the block, used by the documentation generator.
\\\hline
\caption{Attributes common for all description blocks}
\end{tabularx}
%\end{table}
\subsection{PERIPHERAL block attributes}
\textbf{Peripheral} block is the top-level block in the description file.
\newline
Block-specific attributes:
%\begin{table}[h]
\begin{tabularx}{\textwidth}{|p{3cm}|X|}
\hline
\textbf{hdl\us entity}
\newline
(mandatory)
& name of the VHDL entity of the slave core to be generated.
\\\hline
\caption{Attributes specific for \textbf{peripheral} blocks}
\end{tabularx}
%\end{table}
\subsection{REG block attributes}
\textbf{Reg} block describes a single memory-mapped register. Each \textbf{reg} block must contain one or more
\textbf{field} blocks. Available field types are listed in table \ref{table:fieldtypes}.
\newline Block-specific attributes:
%\begin{table}[h]
\begin{tabularx}{\textwidth}{|p{3cm}|X|}
\hline
\textbf{align = val}
\newline
(optional)
& Alignment value for the field address. When given, wbgen2 will align the address of this register to the nearest multiple of \textit{val}. See also figure \ref{fig:regalignment}.
\\\hline
\caption{Attributes specific for \textbf{reg} blocks}
\end{tabularx}
%\end{table}
%\begin{table}[h]
\begin{tabularx}{\textwidth}{|l|X|}
\hline
\textbf{Type} & \textbf{Description}
\\\hline
BIT & VHDL single bit of type \texttt{std\us logic} \\
SLV & VHDL field of type \texttt{std\us logic\us vector} \\
SIGNED & VHDL field of type \texttt{signed} \\
UNSIGNED & VHDL field of type \texttt{unsigned} \\
MONOSTABLE & VHDL field of type \texttt{std\us logic}, generating a single-cycle positive pulse upon bus write of '1'. \\
PASS\us THROUGH & special field, for which wbgen2 will generate only the address decoding logic which provides "wr" signal asserted high for a single WB clock cycle upon each write to the register. The written value will be fed to the corresponding SLV output directly from the Wishbone bus (just wires, no registers in between).
\\\hline
\caption{Possible field types for \textbf{reg} blocks}
\label{table:fieldtypes}
\end{tabularx}
%\end{table}
\InsertDefFig{alignment.pdf}{Register alignment}{fig:regalignment}{0.4}
\subsection{FIELD block}
\textbf{Field} block describes a single register field. There are several types of fields, shown in table \ref{table:fieldtypes}. It's the most elementary block in the design.
\newline
Block-specific attributes:
%\begin{table}[]
\begin{tabularx}{\textwidth}{|p{4cm}|X|}
\hline
\textbf{type}\newline (mandatory)
& type of the field. See table \ref {table:fieldtypes} \\\hline
\textbf{size}\newline (mandatory for: SLV, optional for SIGNED, UNSIGNED)
& size of the field in bits. For SIGNED and UNSIGNED types it's interchangeable with \textbf {range} attribute.\\\hline
\textbf{range = \{min,max\}}\newline (optional for SIGNED, UNSIGNED)
& minimal and maximal field value. When provided, wbgen2 will automatically calculate the necessary number of bits. \\\hline
\textbf{access\us bus}\newline
\textbf{access\us dev}\newline
(optional)
& field access flags. \textbf{access\us bus} defines how the field can be accessed from the Wishbone bus, \textbf{access\us dev} defines how the field can be modified by the HDL entity in which the slave core is instantiated. Access flags can have one of these values: READ\us ONLY, WRITE\us ONLY, READ\us WRITE. For the possible access combinations refer to table \ref{table:accessflags}. \newline
The default value is READ\us WRITE (from the bus) and READ\us ONLY (from the device).
\\\hline
\textbf{access}\newline
(optional)
& can be used instead of \textbf{access\us bus} and \textbf{access\us dev} to define access rights. See table \ref{table:accessflags}.
\\\hline
\textbf{align = num}\newline
(optional)
& when given, the bit offset at which field will be allocated, will be aligned to integer multiple of \textbf{num}. Default value is 1 (no alignment).
\\\hline
\textbf{clock}\newline
(optional)
& can be used to provide a clock port name if the field needs to operate in clock domain other than Wishbone bus clock. wbgen2 will automatically provide the necessary synchronization logic. Clock names are automatically appended to slave core entity port list. If no \textbf{clock} attribute is provided, wbgen2 defaults to Wishbone bus clock.
\\\hline
\textbf{load}\newline
(optional for RW/RW fields)
& this attribute is applicable only to RW/RW-accessed fields (e.g. the fields which are writable both from the bus and the device). There are two possible values, indicating where the field register will be physically placed (see figure \ref{fig:loadintext}):
\newline
\textit{LOAD\us EXT} - the field register is placed outside the slave core. Upon bus write operation, slave outputs the new value to the output port and asserts the "load" signal for a single clock cycle. The device has to handle these signals and update the value of the register respectively.
\newline
\textit{LOAD\us INT} - the field register is placed inside the slave core. When the device wants to update it's value, it passes it to certain input port and asserts the load signal high. \textit{not implemented yet}.
\\\hline
%\caption{Attributes specific for \textbf{field} blocks}
\end{tabularx}
$\end{table}
trunk/software/wbgen2/doc-src/regs.aux 0 → 100644
View file @ dee54890
\relax
\@writefile{toc}{\contentsline {section}{\numberline {3}Registers}{7}{section.3}}
\@writefile{lof}{\contentsline {figure}{\numberline {4}{\ignorespaces wbgen2 register type cheatsheet - standard registers}}{7}{figure.4}}
\newlabel{fig:cheatsheet}{{4}{7}{wbgen2 register type cheatsheet - standard registers\relax }{figure.4}{}}
\@setckpt{regs}{
\setcounter{page}{8}
\setcounter{equation}{0}
\setcounter{enumi}{0}
\setcounter{enumii}{0}
\setcounter{enumiii}{0}
\setcounter{enumiv}{0}
\setcounter{footnote}{0}
\setcounter{mpfootnote}{0}
\setcounter{part}{0}
\setcounter{section}{3}
\setcounter{subsection}{0}
\setcounter{subsubsection}{0}
\setcounter{paragraph}{0}
\setcounter{subparagraph}{0}
\setcounter{figure}{4}
\setcounter{table}{5}
\setcounter{Item}{0}
\setcounter{Hfootnote}{0}
\setcounter{bookmark@seq@number}{0}
\setcounter{lstnumber}{29}
\setcounter{LT@tables}{5}
\setcounter{LT@chunks}{1}
\setcounter{subfigure}{0}
\setcounter{lofdepth}{1}
\setcounter{subtable}{0}
\setcounter{lotdepth}{1}
\setcounter{section@level}{1}
\setcounter{lstlisting}{0}
}
trunk/software/wbgen2/doc-src/regs.tex 0 → 100644
View file @ dee54890
\section{Registers}
wbgen2 supports various types of memory mapped I/O registers and fields:
\begin{itemize}
\item SLV, SIGNED, UNSIGNED and BIT standard registers
\item Bus-synchronous (operating with the same clock as the WB bus) or asynchronous (using externally supplied clock). wbgen2 automatically provides all necessary synchronization logic.
\item MONOSTABLE registers which generate positive pulse upon write of '1'.
'\item PASS\us THROUGH registers
\item Different access configurations
\item Single register can contain fields of different types, clocks and access.
\end{itemize}
Figures \ref{fig:cheatsheet} and \ref{fig:cheatsheetspecial} show all possible register field types.
\InsertDefFig{cheatsheet.pdf}{wbgen2 register type cheatsheet - standard registers}{fig:cheatsheet}{1}
\ No newline at end of file
trunk/software/wbgen2/doc-src/regs.tex~ 0 → 100644
View file @ dee54890
\section{Registers}
wbgen2 supports various types of memory mapped I/O registers and fields:
\begin{itemize}
\item SLV, SIGNED, UNSIGNED and BIT standard registers
\item Bus-synchronous (operating with the same clock as the WB bus) or asynchronous (using externally supplied clock). wbgen2 automatically provides all necessary synchronization logic.
\item MONOSTABLE registers which generate positive pulse upon write of '1'.
'\item PASS\us THROUGH registers
\item Different access configurations
\item Single register can contain fields of different types, clocks and access.
\end{itemize}
Figure \ref{fig:cheatsheet} is a cheatsheet, containing all possible register field types.
\ No newline at end of file
trunk/software/wbgen2/doc-src/title.aux 0 → 100644
View file @ dee54890
\relax
\@setckpt{title}{
\setcounter{page}{2}
\setcounter{equation}{0}
\setcounter{enumi}{0}
\setcounter{enumii}{0}
\setcounter{enumiii}{0}
\setcounter{enumiv}{0}
\setcounter{footnote}{0}
\setcounter{mpfootnote}{0}
\setcounter{part}{0}
\setcounter{section}{0}
\setcounter{subsection}{0}
\setcounter{subsubsection}{0}
\setcounter{paragraph}{0}
\setcounter{subparagraph}{0}
\setcounter{figure}{0}
\setcounter{table}{0}
\setcounter{Item}{0}
\setcounter{Hfootnote}{0}
\setcounter{bookmark@seq@number}{0}
\setcounter{lstnumber}{1}
\setcounter{LT@tables}{0}
\setcounter{LT@chunks}{0}
\setcounter{subfigure}{0}
\setcounter{lofdepth}{1}
\setcounter{subtable}{0}
\setcounter{lotdepth}{1}
\setcounter{section@level}{0}
\setcounter{lstlisting}{0}
}
trunk/software/wbgen2/doc-src/title.log 0 → 100644
View file @ dee54890
This diff is collapsed.
trunk/software/wbgen2/doc-src/title.tex 0 → 100644
View file @ dee54890
\begin{center}
\textsc{European Organization for Nuclear Research}
\\
\textsc{Organisation Europeenne pour la Recherche Nucleaire}
\HRule \\[4cm]
%\includegraphics[width=0.30\textwidth]{./drawings/wr_logo.png}
{\huge \bfseries wbgen2}
\\[1cm]
{\LARGE A simple Wishbone slave core generator}
\\[0.2cm]
{\large Version: \bfseries\DocumentVersion}
\\[8cm]
\end{center}
\begin{minipage}{0.4\textwidth}
\begin{flushleft} \small
Tomasz \textsc{Włostowski}\\
CERN BE-Co-HT\\
\end{flushleft}
\end{minipage}
\begin{center}
\vfill
\HRule\\
\end{center}
trunk/software/wbgen2/doc-src/wbgen2_doc.kilepr 0 → 100644
View file @ dee54890
[General]
kileprversion=2
kileversion=2.0.84
name=wbgen2_doc
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment