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:
Features supported by the latest version:*
- Customizable 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
There are 6 types of blocks:
- peripheral - main block in file, containing the description of entire Wishbone peripheral.
- reg - describing a register
- FIFO - describing a FIFO register
- RAM - describing a RAM memory block
- IRQ - describing an interrupt request line
- field - describing a subfield inside reg or fifo block
Peripheral attributes
Table 2. Peripheral attributes*
| * Attribute *| Status| * Description *|
|hdl_entity
|mandatory|Name of the VHDL entity or Verilog module of the
slave core to be generated|
Register attributes
Table 3. Register attributes*
| * Attribute *| Status| * Description *|
|align = num
|optional|Alignment value for the field address. When
given, wbgen2 will align the address of this register to the nearest
multiple of
num
.
|
Field attributes
Table 4. Register field attributes*
| * Attribute *| Status| * Description *|
|type = BIT
, SLV
, SIGNED
, UNSIGNED
, MONOSTALBLE
,
PASS_THROUGH
|mandatory|Type of the field. See section
#Field-types for detailed description|
|size = num
|mandatory for: SLV
, PASS_THROUGH
optional for: SIGNED
, UNSIGNED
| Size of the field in bits. For
SIGNED
and UNSIGNED
types it's interchangeable with range
attribute |
|range = {min,max}
|optional for: SIGNED
, UNSIGNED
| minimal and
maximal possible field value. When provided, wbgen2 will automatically
allocate the necessary number of bits.|
|access_bus
access_dev
|optional|Field access flags. access_bus
defines how the
field can be accessed from the Wishbone bus, access_dev
defines how
the field can be accessed by the HDL entity connected to the slave core.
Access flags can have one of these values: READ_ONLY
, WRITE_ONLY
,
READ_WRITE
. For the possible access combinations refer to section
registers. The default value is READ_WRITE (from the bus)
and READ_ONLY (from the device).|
|align = num
|optional|Alignment value for the field bit offset. When
given, wbgen2 will align the offset of this field to the nearest
multiple of num
, in the same way it aligns register addresses.|