From fa96cf4a1694afb1ac83e9fc9b894420fc210b97 Mon Sep 17 00:00:00 2001 From: Clifford Wolf Date: Tue, 16 Sep 2014 11:26:44 +0200 Subject: [PATCH] Added new CodingReadme file (replaces CodingStyle and CHECKLISTS) --- CHECKLISTS => CodingReadme | 104 +++++++++++++++++++++++++++++-------- CodingStyle | 43 --------------- kernel/yosys.h | 2 + 3 files changed, 84 insertions(+), 65 deletions(-) rename CHECKLISTS => CodingReadme (57%) delete mode 100644 CodingStyle diff --git a/CHECKLISTS b/CodingReadme similarity index 57% rename from CHECKLISTS rename to CodingReadme index 4a4216512..8f515e1f4 100644 --- a/CHECKLISTS +++ b/CodingReadme @@ -1,17 +1,93 @@ -This file contains checklists for various tasks. +Getting Started +=============== -Table of contents -================= -1. Checklist for creating Yosys releases -2. Checklist for adding internal cell types +Reading List +------------ +To write Yosys C++ code you need to know at least the following classes in kernel/rtlil.h: -1. Checklist for creating Yosys releases + RTLIL::Wire + RTLIL::Cell + RTLIL::Module + RTLIL::SigSpec + +The following yosys commands are a good starting point if you are looking for examples +of how to use the Yosys API: + + passes/opt/wreduce.cc + passes/techmap/maccmap.cc + + +Notes on the existing codebase +------------------------------ + +For historical reasons not all parts of Yosys adhere to the current coding +styles. When adding code to existing parts of the system, adhere to this guide +for the new code instead of trying to mimic the style of the surrounding code. + + + +Coding Style +============ + + +Formatting of code +------------------ + +- Yosys code is using tabs for indentation. Tabs are 8 characters. + +- A continuation of a statement in the following line is indented by + two additional tabs. + +- Lines are as long as you want them to be. A good rule of thumb is + to break lines at about column 150. + +- Opening braces can be put on the same or next line as the statement + opening the block (if, switch, for, while, do). Put the opening brace + on its own line for larger blocks, especially blocks that contains + blank lines. + +- Otherwise stick to the Linux Kernel Coding Stlye: + https://www.kernel.org/doc/Documentation/CodingStyle + + +C++ Langugage +------------- + +Yosys is written in C++11. At the moment only constructs supported by +gcc 4.6 is allowed in Yosys code. This will change in future releases. + +In general Yosys uses "int" instead of "size_t". To avoid compiler +warnings for implicit type casts, always use "SIZE(foobar)" instead +of "foobar.size()". (the macro SIZE() is defined by kernel/yosys.h) + +Use range-based for loops whenever applicable. + + + +Checklist for adding internal cell types ======================================== +Things to do right away: + + - Add to kernel/celltypes.h (incl. eval() handling for non-mem cells) + - Add to InternalCellChecker::check() in kernel/rtlil.cc + - Add to techlibs/common/simlib.v + - Add to techlibs/common/techmap.v + +Things to do after finalizing the cell interface: + + - Add support to kernel/satgen.h for the new cell type + - Add to manual/CHAPTER_CellLib.tex (or just add a fixme to the bottom) + - Maybe add support to the verilog backend for dumping such cells as expression + + + +Checklist for creating Yosys releases +===================================== Update the CHANGELOG file: @@ -116,19 +192,3 @@ In master branch: git commit --amend -am "Yosys x.y.z+" -2. Checklist for adding internal cell types -=========================================== - -Things to do right away: - - - Add to kernel/celltypes.h (incl. eval() handling for non-mem cells) - - Add to InternalCellChecker::check() in kernel/rtlil.cc - - Add to techlibs/common/simlib.v - - Add to techlibs/common/techmap.v - -Things to do after finalizing the cell interface: - - - Add support to kernel/satgen.h for the new cell type - - Add to manual/CHAPTER_CellLib.tex (or just add a fixme to the bottom) - - Maybe add support to the verilog backend for dumping such cells as expression - diff --git a/CodingStyle b/CodingStyle deleted file mode 100644 index e076cbd89..000000000 --- a/CodingStyle +++ /dev/null @@ -1,43 +0,0 @@ - - -Section 0: Notes on the existing codebase ------------------------------------------ - -Not all parts of Yosys adhere to this coding styles for historical -reasons. When adding code to existing parts of the system, adhere -to this guide for the new code instead of trying to mimic to style -of the surrounding code. - - - -Section 1: Formatting of code ------------------------------ - -- Yosys code is using tabs for indentation. Tabs are 8 characters. - -- A continuation of a statement in the following line is indented by - two additional tabs. - -- Lines are as long as you want them to be. A good rule of thumb is - to break lines at about column 150. - -- Opening braces can be put on the same or next line as the statement - opening the block (if, switch, for, while, do). Put the opening brace - on its own line for larger blocks. - -- Otherwise stick to the Linux Kernel Coding Stlye: - https://www.kernel.org/doc/Documentation/CodingStyle - - -Section 2: C++ Langugage ------------------------- - -Yosys is written in C++11. At the moment only constructs supported by -gcc 4.6 is allowed in Yosys code. This will change in future releases. - -In general Yosys uses "int" instead of "size_t". To avoid compiler -warnings for implicit type casts, always use "SIZE(foobar)" instead -of "foobar.size()". (the macro SIZE() is defined by kernel/yosys.h) - -Use range-based for loops whenever applicable. - diff --git a/kernel/yosys.h b/kernel/yosys.h index 9a4826caa..b571e177f 100644 --- a/kernel/yosys.h +++ b/kernel/yosys.h @@ -32,6 +32,8 @@ // // This header is very boring. It just defines some general things that // belong nowhere else and includes the interesting headers. +// +// Find more information in the "CodingReadme" file. #ifndef YOSYS_H -- 2.30.2