\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
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}
\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}
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}
\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}.
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:
