VHDL rational arithmetic package
VHDL Shell Makefile Stata
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
bench/vhdl
rtl/vhdl
sim/rtl_sim
AUTHORS
BUGS
ChangeLog
LICENSE
README.html
README.pdf
README.rst
THANKS
TODO
VERSION
ratpack.png
rst2docs.sh

README.rst

ratpack user manual

ratpack.png

Title ratpack (VHDL rational arithmetic package).
Author Nikolaos Kavvadias 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016
Contact nikos@nkavvadias.com
Website http://www.nkavvadias.com
Release Date 23 July 2016
Version 0.3.5
Rev. history  
v0.3.5

2016-23-07

Use sim/rtl_sim/bin dir, ignores for git, clean script

v0.3.4

2016-03-12

Updates dates, Changelog.

v0.3.3

2014-11-29

Added project logo in README.

v0.3.2

2014-10-14

Replaced COPYING by LICENSE.

v0.3.1

2014-09-22

New features and changes:

  • Testing of max, rmin (min), rmax (max).
  • Automatic end of simulation (via forced assert).
  • Renamed run.sh to ghdl.sh.
  • Added mti.sh and ratpack_tb1/tb2.do for Modelsim.
  • README update.
v0.3.0

2014-09-22

Updated for github (contents of /doc moved to top-level directory, minor documentation changes).

v0.2.0

2014-02-21

Changed documentation format to RestructuredText. Code has been reorganized into new directory structure.

v0.1.3

2010-11-17

Added max, min.

v0.1.2

2010-11-17

Added gcditer (iterative GCD using rational numbers).

v0.1.1

2010-06-07

Minor update in documentation (README).

v0.1.0

2010-05-14

First public release.

1. Introduction

ratpack is a rational arithmetic package written in VHDL.

Currently, the ratpack package implements the following:

  • the RATIONAL data type.
  • to_rational: construction function of a rational given two integers (numerator and denominator).
  • int2rat: conversion function of an integer to its rational representation.
  • numerator: extracts the numerator of a rational number.
  • denominator: extracts the denominator of a rational number.
  • "+", "-", "*", "/": implementation of the basic arithmetic operations for rationals.
  • abs: extracts the absolute value of a given rational number.
  • max: extracts the maximum of two rationals.
  • min: extracts the minimum of two rationals.
  • ">", "<", ">=", "<=", "=", "/=": overload comparison operators for rationals.
  • gcd: computes the greatest common divisor of two integers (positive, covers the pathological case of division by zero).
  • mediant: computes the mediant rational of two given rationals.

ratpack is distributed along with two VHDL testbenches: a simple one (ratpack_tb1.vhd) and a testbench generating the Farey series of orders 1 to 12 (ratpack_tb2.vhd). An exemplary rational arithmetic ALU has also been included but it is currently left untested (not testbench for it).

The ratpack project can be download from the following OpenCores website: http://opencores.org/project,ratpack

An up-to-date version of the ratpack code base is also maintained on Github: http://github.com/nkkav/ratpack.git

2. File listing

The ratpack distribution includes the following files:

/ratpack Top-level directory
AUTHORS List of ratpack authors.
BUGS Bug list.
ChangeLog A log for code changes.
LICENSE The modified BSD license governs ratpack.
README.rst This file.
README.html HTML version of README.
README.pdf PDF version of README.
ratpack.png PNG image for the ratpack project logo.
rst2docs.sh Bash script for generating the HTML and PDF versions.
THANKS Acknowledgements.
TODO A list of future enhancements.
VERSION Current version of the project sources.
/bench/vhdl Testbench source code directory for the package
ratpack_tb1.vhd A simple testbench.
ratpack_tb2.vhd Testbench generating the Farey series (orders 1-12).
/rtl/vhdl RTL source code directory for the package
ratalu.vhd Implementation of a rational arithmetic ALU.
ratpack.vhd The rational arithmetic package.
/sim/rtl_sim RTL simulation files directory
/sim/rtl_sim/bin RTL simulation makefiles directory
ratpack.mk GNU Makefile for running GHDL simulations.
ratpack_tb1.do Modelsim .do script for running the simulation for testbench ratpack_tb1.vhd.
ratpack_tb2.do Modelsim .do script for running the simulation for testbench ratpack_tb2.vhd.
/sim/rtl_sim/out RTL simulation output files directory
ratpack_results1.txt Output generated by the ratpack_tb1.vhd tests.
ratpack_results2.txt Output generated by the ratpack_tb2.vhd tests.
/sim/rtl_sim/run RTL simulation run scripts directory
clean.sh A bash script for cleaning simulation artifacts.
ghdl.sh A bash script for running the GNU Makefile for GHDL.
mti.sh A bash script for running the Mentor Modelsim simulation for either testbench.

3. ratpack usage

Contents of the ratpack distribution can be simulated using either GHDL or Mentor Modelsim using the provided scripts.

3.1. GHDL

The ratpack package test script for GHDL can be used as follows:

$./ghdl.sh <package/entity name> <test case>

from within directory ratpack/sim/rtl_sim/run.

After this process, the ratpack_results.txt file is generated containing simulation results.

Here follow some simple usage examples of this bash script.

  1. Compile the ratpack package and do a simple test.
$ cd sim/rtl_sim/run
$ ./ghdl.sh ratpack 1

The default results for comparison can be found as sim/rtl_sim/out/ratpack_results1.txt

  1. Compile the ratpack package and generate the Farey series.
$ ./ghdl.sh ratpack 2

The default results for comparison can be found as sim/rtl_sim/out/ratpack_results2.txt

The run script expects that the GHDL simulator is installed and its bin directory is in the $PATH.

3.2 Modelsim

For running the Modelsim simulation, the ratpack package test script for can be used as follows:

$./mti.sh <package/entity name> <test case>

from within directory ratpack/sim/rtl_sim/run.

  1. Compile the ratpack package and do a simple test.
$ cd sim/rtl_sim/run
$ ./mti.sh ratpack 1

As in the GHDL case, a diagnostic text file is produced. The default results for comparison can be found as sim/rtl_sim/out/ratpack_results1.txt

  1. Compile the ratpack package and generate the Farey series.
$ ./mti.sh ratpack 2

The default results for comparison can be found as sim/rtl_sim/out/ratpack_results2.txt

4. Prerequisites

  • Standard UNIX-based tools (tested on cygwin/x86 and MinGW/x64)

    • make
    • bash
  • GHDL simulator (http://ghdl.free.fr)

    Provides the "ghdl" executable and corresponding simulation environment.

  • Alternatively to GHDL, the Mentor Modelsim simulator (http://www.mentor.com)