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
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.
The extensions should be .hpp/.cpp for C++ headers/code.
C++ files should have the same name and case than the class they contain. For example class FPAdder should be declared in file FPAdder.hpp and implemented in FPAdder.cpp.
Source code should use UTF8 character set.
Variable names and comments should be in English.
Class names are nouns, in mixed-case, with an initial upper-case letter and the first letter of each subsequent word capitalized (e.g. TestBench).
Method names are verbs or nouns in mixed-case, starting with a lower-case letter (e.g. update() or addElement()).
Methods that return a value should take the form getSize().
The names of local variables should be in mixed case, starting with a lower-case letter (e.g. countDepth). This also applies to the formal parameters of methods. Do not use names starting with underscore.
Private and protected data member names must end with underscore "_"
The names of macros or static const
should be all upper-case words, separated by underscore:
#define MIN_WIDTH 3 static const string VERSION = "0.8";
Indentation should be done with tabs, not spaces. This allows each developers to use his favorite indent size without changing the code.
Preferred layout for braces:
void MyClass::myMethod(int x){
if (x>10){
cout << "Some text" << endl;
}
}
When wrapping lines from long function calls, where the wrapped line does not start at the same level of indentation as the start of the function call, tab up to the start of the function call, and then use spaces to the opening parenthesis.
[--tab-][--tab-][--tab-]someFunction(param, ... [--tab-][--tab-][--tab-][ spaces ]moreparams, ...);
enums should follow the QT conventions. i.e. CamelCase with First letter capitalization for both enum type and enum values. Should be document with doxygen. The /**< tag */ can be used to add descriptions on the same line as an enum value, e.g.
/** @enum EnumName Here is a description of the enum *
enum EnumName {
EnumValueOne, /**< Some doxygen description of EnumValueOne */
EnumValueTwo, /**< Some doxygen description of EnumValueTwo */
EnumValueThree /**< Some doxygen description of EnumValueThree */
};
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.