FloPoCo user manual

Installation

FloPoCo depends on the MPFR library, available from http://www.mpfr.org and probably available in your favourite Linux/Unix distribution. To compile it you need CMake (http://www.cmake.org/) which also comes prepackaged for mainstream Linux/Unix distributions.

Optionally, you may want to link FloPoCo against Sollya. This enables more operators (HOTBM, CRFPConstMult). For this purpose, you must download, compile and install Sollya. FloPoCo is demonstrated to work with version 1.1 of Sollya and should work with future releases.

Compilation is a two-step process:

cmake .

make

The adventurous may get FloPoCo from its subversion repository.

Command-line interface

FloPoCo is a command-line tool. The general syntax is

flopoco <options> <operator specification list>

FloPoCo will generate a single VHDL file (named by default flopoco.vhdl) containing synthesisable descriptions of all the operators listed in <operator specification list>, plus possibly sub-operators instanciated by them. To use these operators in your design, just add this generated file to your project.

FloPoCo will also issue a report with useful information about the generated operators, such as the pipeline depth or expected working frequency.

Examples

./flopoco IntConstMult 16 12345

produces a file flopoco.vhdl containing a single operator for the integer multiplication of an input 16-bit number by the constant 12345. The VHDL entity is named after the operator specification, here IntConstMult_16_12345.

./flopoco IntConstMult 16 12345 IntConstMult 16 54321

produces a file flopoco.vhdl containing two VHDL entities and their architectures, for the two given constant multipliers.

./flopoco FPConstMult 8 23 8 23 0 -50 1768559438007110

produces a file flopoco.vhdl containing two VHDL entities, one for the specified constant floating-point multiplier by 1768559438007110x2^-50, and the other one for a needed sub-component (an integer multiplier for the significand multiplication).

Options

Several transversal options are available and will typically change the operators occuring after them in the list. For instance -frequency=300 sets the target frequency. The -name=UserProvidedName option replaces the (ugly and parameter-dependent) name generated by FloPoCo for the next operator with a user-provided one. This allows in particular to change parameters while keeping the same entity name, so that these changes are transparent to the rest of the project. Options related to pipelining are reviewed below.

Built-in help

To obtain a concise list of the available operators and options, simply type

./flopoco

In addition this help may be more in sync with the code than this file, especially if you are using a svn snpashot.

Helper programs

The FloPoCo distributions also includes useful programs for converting the binary string of a floating-point number to human-readable form (bin2fp) and back (fp2bin). The longacc2fp utility converts the fixed-point output of the LongAcc operator (see below) to human-readable form.

Floating-point format

The floating-point format used in FloPoCo is identical to the one used in FPLibrary. It is inspired from the IEEE-754 standard, from which it differs only for exceptional cases (zeroes, infinities and Not a Number or NaN).

An FP number is a bit vector consisting of 4 fields. From left to right:

A 2-bit exception field: 00 for zero, 01 for normal numbers, 10 for infinities, and 11 for NaN
A sign bit: 0 for positive, 1 for negative
An exponent field on wE bits: It is biased as in IEEE-754. The smallest possible FP numbers have exponent field 00...00, the FP number 1.0 has the exponent field 011...11 and the largest possible FP numbers have exponent 11...11
A fraction field on wF bits: The actual significand has an implicit leading 1, so the fraction field ff...ff represents the significand 1.ff...ff

The format is therefore parameterized by to positive integers wE and wF which define the sizes of the exponent and fraction fields respectively.

The utilities fp2bin and bin2fp will allow you to get familiar with the format and set up test benches.

LNS format

Numbers in the Logarithm Number System used in FloPoCo have an encoding similar to the floating-point format, which is also the same as the one used in FPLibrary.

Its fields are:

A 2-bit exception field: Same encoding as floating-point: 00 for zero, 01 for the general case, 10 for infinities, and 11 for NaN
A sign bit: 0 for positive, 1 for negative
The integral part of the exponent on wE bits
The fractional part of the exponent on wF bits: The fixed-point exponent is encoded in two's-complement.

Pipelining

Two command-line options control the pipelining of the FloPoCo operators that follow them.

-pipeline=[yes|no] (default yes): Requires the operators to be pipelined. If yes, at least one register will be inserted (at the output of the operator), and maybe more inside the operator. If no, the operator will be combinatorial.
-frequency=[frequency in MHz] (default 300): Sets the target frequency. If the -pipeline option is set, then FloPoCo will try to pipeline the operator to the given frequency. It will report a warning if it fails -- or if frequency-directed pipelining is not yet implemented for this operator.

The philosophy of FloPoCo's approach to pipelining is the following:

FloPoCo's approach is to provide a fair estimate of the pipeline depth required to obtain a given frequency, and a sensible placement of registers.
FloPoCo's pipelining effort is always tentative: You may not get the frequency you asked (sometimes you will even get a higher one). However, in such cases, increasing or decreasing the target frequency should also increase or decrease the obtained frequency.
Better results will always be obtained by using retiming tools, which can work on a circuit netlist after technology mapping. The pipeline built by FloPoCo should help these retiming tools converge faster to a global optimal.

Note that not all operators support pipelining (utimately they all will). They are mentionned in the command-line help.

Available operators

Here is the list of operators that can be generated by FloPoCo. This list may not be fully up-to date... the code is the reference.

Useful building blocks for FP operators

LeftShifter wIn MaxShift: Left barrel shifter. It has two inputs, the data to shift and a shift value. The width of the latter is deduced from MaxShift, which is the maximum shift distance. This operator will be pipelined to match target frequency.
RightShifter wIn MaxShift: Same, but to the right.
LZOC wIn wOut: Leading Zero/One Counter.
LZOCShifterSticky wIn wOut computeSticky countType: Leading Zero/One Counter merged with a shifter. If computeSticky=0 the bits shifted out are discarded, if 1 they are ORed into a sticky bit. If countType=0, a leading zero counter is built, if 1 a leading one counter is built, if -1 the value to count is input from an extra input port.

Pipelined integer standard operators

IntAdder wIn: Integer adder. In modern VHDL, integer addition is expressed by a + and one usually needn't define an entity for it. However, this operator will be pipelined if the addition is too large to be performed at the target frequency.
IntMultiplier wInX wInY: Same for multiplication, although the frequency attainable will be limited by the DSP blocks available. wInX and wInY are the input widths of both operands. This is an unsigned operation.

Classical floating-point operators

FPMultiplier wEX wFX wEY wFY wER wFR: A floating-point multiplier, with pepper: it may multiply numbers of different precisions, and provide you with the correct rounding to arbitrary precision -- including an exact result if wFR is larger than wFX+wFY+1.
FPAdder wEX wFX wEY wFY wER wFR: A floating-point adder. Currently the three wE must be equal and the three wF must be equal. Eventually it should add numbers of different precisions, and provide you with the correct rounding to arbitrary precision.

Long fixed-point accumulator, and derivatives

These operators are described in all the gory details in this article.

LongAcc wE_in wF_in MaxMSB_in LSB_acc MSB_acc: Long fixed-point accumulator. By tuning the MaxMSB_in, LSB_acc and MSB_acc parameters to a given application, it allows one to bring rounding error to a provably arbitrarily small level (and in some case to avoid any rounding), for a very small hardware cost compared to using a floating-point adder for accumulation.
DotProduct wE_in wF_X wF_Y MaxMSB_in LSB_acc MSB_acc: Dot product operator. It feeds a long accumulator with the unrounded result of a floating-point multiplier, thus removing rounding errors from the multiplication as well.
LongAcc2FP MaxMSB_in LSB_acc MSB_acc wE_out wF_out: Post-normalisation unit for LongAcc. It converts the output of a LongAcc or DotProduct (with the same parameters) into a floating-point number.

Constant multipliers

This family of operators is described in all the gory details in this article.

IntConstMult w c: integer constant multiplier: w is input size, c is the constant.
FPConstMult wE_in wF_in wE_out wF_out cst_sgn cst_exp cst_int_sig: floating-point constant multiplier. The constant is provided as sign, integral significand and integral exponent.

Floating-point elementary functions

FPExp wE wF: An exponential operator, where both inputs and outputs have wE bits exponent and wF bits significand. This operator implements the exponential function as described in this article.
FPLog wE wF: A natural logarithm operator, where both inputs and outputs have wE bits exponent and wF bits significand. This operator implements the natural logarithm function as described in this article.

HOTBM

This operator implements an arbitrary function using High-Order Table-Based Method, best described in this article.

HOTBM func wI wO degree
HOTBMFX func wE_in wF_in wE_out wF_out degree
HOTBMRange func wI wO degree xmin xmax scale: HOTBM implementation of a function. func is a sollya-like expression of the function, wI is the input width, wO is the output width and degree is the degree of the Remez polynomial. wE_in, wF_in, wE_out, wF_out are the width of the integral and fractional parts of the input and the output, respectively. [xmin, xmax] is the input domain of the function, and scale is a scaling factor to be applied to the output.

For HOTBM the input operand is interpreted as a positive fixed-point number, with the point before the leftmost bit. The function to be implemented is assumed to be well defined in [0;1[. The output is a fixed-point number, where the first bit is the sign and the point is placed right after it. Note that the output is in fact wO+1 bits wide.

Due to the fact that the expression of the function might contain characters which are treated specially by the shell, you should enclose it within quotes.

Example:
flopoco HOTBM "sin(x*Pi/2)" 16 16 3

The HOTBMFX version allows to select arbitrary fixed-point representations for the input and output. Negative values are allowed.

Example:
flopoco HOTBMFX "log2(1+2^(-x))" 2 8 -1 8 1

HOTBMRange uses HOTBM after mapping [xmin,xmax[ to [0,1[, then multiplies the output by the scaling factor scale.

Note that this launches an exploration process that typically takes a few minutes for 16 bits, and may take hours for 24 bits.

HOTBM uses a polynomial approximation. It works well for functions which are regular enough (in mathematical terms, they should be defined and n-times continuously differentiable on the domain).

LNS

These operators compute in the Logarithmic Number System. They are mostly useful for low-precisions systems performing few additions and many multiplications, divisions or square roots.

LNSAddSub wE wF: LNS addition operator. Both operands and the output have wE integral bits and wF fractional bits in their exponents.
LNSMul wE wF: LNS multiplication operator. Both operands and the output have wE integral bits and wF fractional bits in their exponents.
LNSDiv wE wF: LNS division operator. Both operands and the output have wE integral bits and wF fractional bits in their exponents.
LNSSqrt wE wF: LNS square root operator. Both input and output have wE integral bits and wF fractional bits in their exponents.

Test Benches

The TestBench operator will generate a test bench for the operator which precedes it in the command line (also called unit under test, UUT). Test cases are highly UUT specific. They include both standard tests and random tests. The single parameter of the TestBench specifies the number of random tests to generate. Random tests are generating using a pseudo-random number generator, being initialised with the same seed, so that the test bench will be deterministic. Currently, only the following operators are able to generate test cases required for test bench generation: HOTBM, IntMultiplier, FPAdder, FPMultipier, IntConstMult, FPConstMult, FPExp, FPLog.

Example:
flopoco HOTBM "sin(x*Pi/2)" 16 16 3 TestBench 1000

BigTestBench is similar to TestBench but is optimized for large tests (up to 1 million). It generates a very short VHDL code, which reads test vectors from a predetermined file (the filename is operator_unique_name.test). However, BigTestBench has the disadvantage that the test file looks like a big blob and it is very hard to debug problems, especially for pipelined designs. Therefore, it is recommended to use this operator only when TestBench is successful, and one wants to be really sure that the UUT is working perfectly.

Example:
flopoco FPExp 8 16 BigTestBench 200000

Miscellanous

Wrapper: Produce a wrapper for the preceding operator (useful to get synthesis results without having the operator optimised out).