wbgen2 Documentation
1. Introduction
In wbgen2 terminology, a ”slave core” is an 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 the following figure:
wbgen2 simplifies creation of such cores, by automatically generating HDL code, C code and documentation from a single, easily editable file.
Features supported by the latest version:*
- Customisable register types, with multiple access options and multiple clocking schemes
- Configurable memory blocks
- Peripheral-level interrupts via Embedded Interrupt Controller
- Generation of VHDL/Verilog synthesizable code
- Automatic address space layout generation
- Generation of C header files containing memory map consistent with the HDL core
- Support for popular synthesizable VHDL data types
Foreseen in near future*
- FIFO register support
- Pipelined Wishbone support
The primitives are accessible from outside the slave core as VHDL/Verilog signals:
2. Input file syntax
In order to generate anything, wbgen2 requires a file (later referred as WB* file) with a description of what we want to have inside the slave core. The syntax of description files is very similar to C language, hence they are easily editable without need for any special tools (unlike XML-based formats). Each WB file contains description of a single peripheral which may consist of:
- Registers
- RAM blocks
- FIFO registers
- Interrupt lines
Registers and FIFO registers can be split into fields of different types and sizes, as shown on the figure below:
General syntax of WB file looks like:
<code class="C">
block {
attribute1 = "string";
attribute2 = 1234;
block {
attribute3 = ....;
block { ... };
};
};
</code>
2.1. Common attributes
Common attributes* apply for all blocks in the WB file. Currently there are 3 common attributes (object name, description and prefixes - see table 1).
Some of the attributes are mandatory - they always have to be defined, while the others may be optional.
Table 1. Common attributes*
| * Attribute *| Status| * Description *|
|name
| mandatory | Short (single line) human readable name for the
block. The name is used for commenting the generated code and producing
documentation. |
|description
| optional | Longer description of the block, used by the
documentation generator. May contain inline HTML code. |
|c_prefix
, hdl_prefix
, prefix
| 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:
peripheral_reg_field
. In this
example, the
signal name of register "DDR" would be gpio_ddr_o
. The format of
prefix
value must follow the HDL/C language syntax rules and your
coding style. Note that you can provide either separate prefixes for
C/HDL languages c_prefix
, hd_prefix
a single prefix
for both. |
2.2. Object-specific attributes
Object-specific attributes apply only to blocks of certain type (for example, width attribute applies only to RAM memory or trigger attribute is valid only for interrupt block). Detailed descriptions are provided in peripheral, register, RAM, FIFO and IRQ block sections.
3. wbgen2 design blocks
Peripheral block
3.1.Main block in file, representing an entire Wishbone peripheral.
Register (reg) block.
3.2.Block describing a memory-mapped register.
FIFO register (fifo) block
3.3.Block describing a memory-mapped FIFO register.
RAM memory (ram) block
3.4.Block describing a RAM memory.
Interrupt request line (irq) block
3.5.Block describing an configurable IRQ line
4. Using wbgen2
4.1. Command line options
$ ./wbgen2 --help
slave Wishbone generator
wbgen2 [options] input_file.wb
options:
-C, --co=FILE Write the slave's generated C header file to FILE
-f, --docformat=FORMAT Write documentation for latex, texinfo or HTML (defaults to HTML)
-D, --doco=FILE Write the slave's generated documentation to FILE
-h, --help Show this help text
-l, --lang=LANG Set the output Hardware Description Language (HDL) to LANG
Valid values for LANG: {vhdl,verilog}
-s, --cstyle=STYLE Set the style of register bank in generated C headers
Valid values for STYLE: {struct, defines}
-H, --hstyle=STYLE Set the style of register signals in generated VHDL/Verilog file
Valid values for STYLE: {signals, record}
-K, --constco=FILE Populate FILE with Verilog output (mainly constants)
-v, --version Show version information
-V, --vo=FILE Write the slave's generated HDL code to FILE
-p, --vpo=FILE Generate a VHDL package for slave's generated VHDL
(necessary with --hstyle=record)
wbgen2 (c) Tomasz Wlostowski/CERN BE-CO-HT 2010-2012
4.2. Running wbgen2 under Windows
# Go to the Files section of the project webpage.
# Download the latest binary package, that comes with a built-in Lua interpreter.
# Unpack the archive and put wbgen2.exe
in a directory that is within
the search PATH.
# Run with the following command:
wbgen2 [options] input_file.wb
Example to generate vhdl code and html documentation:
wbgen2 -l vhdl -V output_file.vhd -f html -D output_file.htm input_file.wb