libvhdl/README.md

# libvhdl
A LGPLv3 licensed library of reusable components for VHDL designs and testbenches


##sim
(Non) synthesible components for testbenches

##### AssertP
Package with various assertion procedures.

* `assert_true(x[, str, level])` checks if boolean x = false
* `assert_false(x[, str, level])` checks if boolean x = false
* `assert_equal(x, y[, str, level])` checks if x = y
* `assert_unequal(x, y[, str, level])` checks if x /= y

All of the assert_* procedures have following optional parameters:

* `str` print string str to console instead implemented one
* `level` severity level (note, warning, error, failure)

##### SimP
Package with various components general useful for simulation

* `wait_cycles(x, n)` waits for n rising edges on std_logic signal x
* `spi_master()` configurable master for SPI protocol, supports all cpol/cpha modes
* `spi_slave()` configurable slave for SPI protocol, supports all cpol/cpha modes

##### QueueP
Package with various implementations of queue types:

* `t_simple_queue` simple array based FIFO queue
* `t_list_queue` linked list FIFO queue using access types


## syn
Synthesizable components for implementing in FPGA

##### SpiMasterE
Configurable SPI master with support modes 0-3 and simple VAI local backend.

##### SpiSlaveE
Configurable SPI slave with support modes 0-3 and simple VAI local backend.



##test
Unit tests for each component

##### QueueT
Unit tests for components of QueueP package

##### SimT
Unit tests for components of SimP package

##### SpiT
Unit tests for SpiSlave component


## Dependencies
To run the tests, you have to install GHDL. You can get it from
[http://sourceforge.net/projects/ghdl-updates/](http://sourceforge.net/projects/ghdl-updates/).

Furthermore, you need the VHDL 2008 proposed packages because libvhdl uses various VHDL 2008 features.
You can get the packages from [http://www.eda.org/fphdl/](http://www.eda.org/fphdl/).
Save the following files into the vhdl_2008/ folder in the test directory:

* standard_additions_c.vhd
* standard_textio_additions_c.vhd
* std_logic_1164_additions.vhd
* numeric_std_additions.vhd
* numeric_std_unsigned_c.vhd
* env_c.vhd

If you another simulator with full VHDL-08 support, you don't need these packages. Instead you have to outcomment
the references to these packages from the source files.

libvhdl also uses the OSVVM library to generate random data for the unit tests. We use version OSVVM version 2.1
because of restrictions of the current GHDL release. You can find it under the osvvm_2.1 folder in the test/
directory. If you use another simulator with full OSVVM support, you can download newer versions of the library
from [http://osvvm.org](http://osvvm.org).

Another useful tool is GTKWave, install it if you want to use the waveform files generated by some of the tests.


## Building
Type `make` to do all tests. You should see the successfully running tests like this:

```
$ make
ghdl -a --std=02 ../sim/QueueP.vhd QueueT.vhd
ghdl -e --std=02 QueueT
ghdl -r --std=02 QueueT
QueueT.vhd:52:5:@0ms:(report note): INFO: t_simple_queue test finished successfully
QueueT.vhd:87:5:@0ms:(report note): INFO: t_list_queue test finished successfully
```