Getting started with FloPoCo

Welcome to new developers!

If you are unfamiliar with the cmake system, there is little to learn, really. When adding .hpp and .cpp files to the project, you will need to edit CMakeLists.txt. It is probably going to be straightforward, just do some imitation of what is already there. Anyway cmake is well documented.

In FloPoCo, everything is an Operator. Go read Operator.hpp first.

Operator is a virtual class. For an example of simple Operator, go read IntAdder. Addition is written as + in modern VHDL, but the class IntAdder implements adders pipelined to arbitrary frequency, so you'll get an idea on how FloPoCo implements frequency-directed pipelining.

For a more complex class with subcomponents, go read FPAdder. It instantiates several IntAdders, leading zero counters and shifters, asks them their pipeline depth, then builds its own pipeline out of this information. There should be a figure in the doc/Figures directory. This class is also an example of the best way to write a single code for both a pipelined operator and the combinatorial version.

To understand the command line, go read main.cpp. It is not the part we are the most proud of, but it does the job.

The rest is arithmetic!

And do not hesitate to contact us: Florent.de.Dinechin, à ens-lyon.fr



FloPoCo Coding Standards

As the complexity and size of this project increase, it feels necessary to define a set of coding rules and guidelines in order to have a clean an consistent code.

File Names

Stylistic conventions

Doxygen Comments

FloPoCo source code should be documented with Doxygen. From Doxygen webpage:

"Doxygen is a documentation system for C++, C, Java, [...] It can generate an on-line documentation browser (in HTML) and/or an off-line reference manual (in LaTeX) from a set of documented source files. [...] The documentation is extracted directly from the sources, which makes it much easier to keep the documentation consistent with the source code. [...] You can also visualize the relations between the various elements by means of include dependency graphs, inheritance diagrams, and collaboration diagrams, which are all generated automatically.

(Quote extracted from the Sellarium Project webpage)

All public and protected classes and methods from FloPoCo should be fully documented in the headers (.hpp).

There are different ways to comment C++ code with Doxygen, in FloPoCo use the following for headers files:

/**
 * Adds a TestCase to this TestCaseList. 
   Detailled description
 *@param t TestCase to add<
 */
void add(TestCase t);

Brief descriptions are single line only, and stop at the first full stop (period). Any subsequent sentences which occur before @param or a similar tag are considered to be part of a detailed description.

Stylistic conventions for generated VHDL

... may be formalized some day. Currently, the main advice is to use helper functions of the Operator class as much as possible.