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. In addition, three levels of verbosity are available.
To obtain a concise list of the available operators and options, simply type
./flopoco IntConstMult wIn=16 c=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
./flopoco IntConstMult wIn=16 c=12345 IntConstMult wIn=16 c=54321
produces a file
flopoco.vhdl containing two VHDL entities and their architectures, for the two given constant multipliers.
Several transversal options are available and will typically change the operators occuring after them in the list.
target=Virtex5sets the target hardware family. For a list of supported families see the command line. We typically target the highest speed grade available for a family (see below for pipelining options).
frequency=300sets the target frequency (in MHz).
name=UserProvidedNamereplaces the (ugly and parameter-dependent) entity name generated by FloPoCo for the next operator. 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.
plainVHDL=yesinstructs FloPoCo to output concise and readable VHDL, using only + and * VHDL operators instead of FloPoCo adders and subtractors. This helps understanding the algorithms used by FloPoCo, but typically prevents or degrades automatic pipelining.
useHardMult=noinstructs FloPoCo not to use hard multipliers or DSP block
unusedHardMultThreshold=0.3instructs FloPoCo to use a hard multiplier (or DSP block) if less than 30% of this hard multiplier are unused. The ratio is between 0 and 1, such that 0 means: any sub-multiplier that does not fully fill a DSP goes to logic; 1 means: any sub-multiplier, even very small ones, will consume a DSP
The FloPoCo distributions also includes useful programs for converting the binary string of a floating-point number to human-readable form
bin2fp) and back (
longacc2fp utility converts the fixed-point output of the LongAcc operator (see below) to human-readable form.
Don't trust FloPoCo, test its operators: the provided TestBench operator builds a VHDL test bench for the operator preceding it. These test benches are generated out of the mathematical specification of the operator, and can be trusted. For instance
will generate a testbench with a selection of regression and corner-case tests and 10000 random tests. It also prints on the terminal how to run this test.
./flopoco FPAdd wE=7 wF=21 TestBench n=10000
The floating-point format used in FloPoCo is identical to the one used in FPLibrary. It is inspired from the IEEE-754 standard.
An FP number is a bit vector consisting of 4 fields. From left to right:
The format is therefore parameterized by to positive integers wE and wF which define the sizes of the exponent and fraction fields respectively.
bin2fp will allow you to get familiar with the format and set up test benches.
There are two main differences between the format (wE=8, wF=23) and the IEEE-754 single precision format (the same holds for double).
Exceptional cases (zeroes, infinities and Not a Number or NaN) are encoded as separate bits in FloPoCo, instead of being encoded as special exponent values in IEEE-754. This saves quite a lot of decoding/encoding logic. The main drawback of this format is when results have to be stored in memory, where they consume two more bits. However, FPGA embedded memory can accomodate 36-bit data, so adding two bits to a 32-bit IEEE-754 format is harmless as long as data resides within the FPGA.
As a side effect, the exponent can take two more values in FloPoCo than in IEEE-754 (one for very large numbers, one for very small ones).
x-y=0 <=> x=y. With flush to zero as used in FloPoCo, x and y can be close enough that their difference is flushed to zero, while not being equal.
Note that anyway, FloPoCo provides conversion operators from and to IEEE-754 formats (single and double precision).
Numbers in the Logarithm Number System used in FloPoCo have an encoding similar to the floating-point format. It is also the same as the one used in FPLibrary.
Its fields are:
Reasonable values are 4 to 8 for wE, and 8 to 20 for wF. Other values are still allowed, including negative wE. Use at your own risk.
An operator may be combinatorial, or pipelined. A combinatorial operator has pipeline depth 0. An operator of pipeline depth 1 is obtained by inserting one and only one register on any path from an input to an output. Hopefully, this divides the critical path delay by almost 2. An operator of pipeline depth 2 is obtained by inserting two register levels, etc.
It should be noted that, according to this definition, pipelined operators usually do not directly buffer neither their inputs nor their outputs. For instance, connecting the input of a 400MHz operator to the output of another 400MHz operator may well lead to a circuit working at 200MHz only. It is the responsibility of the user or calling program to insert one more level of registers between two FloPoCo operators. This convention may be felt as a burden to the user, but it is the most sensible choice. It makes it possible to assemble sub-component without inserting registers in many situations, thus reducing the latency of complex components. Besides, different application contexts may have different policies (registers on output, or registers on input).
The following command-line option controls the pipelining of the FloPoCo operators that follow them.
frequency=[frequency in MHz]
pipelineoption 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 FPAdd frequency=200 wE=11 wF=53 FPMult frequency=300 wE=8 wF=23
-frequencyoption may save resources.
Note that not all operators support pipelining (utimately they all will). They are mentionned in the command-line help.