From: Clifford Wolf Date: Tue, 16 Sep 2014 09:26:44 +0000 (+0200) Subject: Added new CodingReadme file (replaces CodingStyle and CHECKLISTS) X-Git-Tag: yosys-0.4~122 X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=fa96cf4a1694afb1ac83e9fc9b894420fc210b97;p=yosys.git Added new CodingReadme file (replaces CodingStyle and CHECKLISTS) --- diff --git a/CHECKLISTS b/CHECKLISTS deleted file mode 100644 index 4a4216512..000000000 --- a/CHECKLISTS +++ /dev/null @@ -1,134 +0,0 @@ - -This file contains checklists for various tasks. - - -Table of contents -================= - -1. Checklist for creating Yosys releases -2. Checklist for adding internal cell types - - -1. Checklist for creating Yosys releases -======================================== - - -Update the CHANGELOG file: - - cd ~yosys - gitk & - vi CHANGELOG - - -Run all tests with "make config-{clang-debug,gcc-debug,gcc-4.6,release}": - - cd ~yosys - make clean - make test vloghtb - make install - - cd ~yosys-bigsim - make clean - make full - - cd ~vloghammer - make purge - make gen_issues gen_samples - make SYN_LIST="yosys" SIM_LIST="icarus yosim verilator" FULL=1 world - chromium-browser report.html - - -Then with default config setting: - - cd ~yosys - ./yosys -p 'proc; show' tests/simple/fiedler-cooley.v - ./yosys -p 'proc; opt; show' tests/simple/fiedler-cooley.v - - cd ~yosys - make manual - - sanity check the figures in the appnotes and presentation - - if there are any odd things -> investigate - - make cosmetic changes to the .tex files if necessary - - -Also with default config setting: - - cd ~yosys/techlibs/cmos - bash testbench.sh - - cd ~yosys/techlibs/xilinx/example_sim_counter - bash run_sim.sh - - cd ~yosys/techlibs/xilinx/example_mojo_counter - bash example.sh - - -Finally if a current verific library is available: - - cd ~yosys - cat frontends/verific/build_amd64.txt - - follow instructions - - cd frontends/verific - ../../yosys test_navre.ys - - -Release candiate: - - - create branch yosys-x.y.z-rc and push to github - - contact the usual suspects per mail and ask them to test - - post on the reddit and ask people to test - - commit KISS fixes to the -rc branch if necessary - - -Release: - - - set YOSYS_VER to x.y.z in Makefile - - update version string in CHANGELOG - git commit -am "Yosys x.y.z" - - - push tag to github - - post changelog on github - - post short release note on reddit - - delete -rc branch from github - - -Updating the website: - - cd ~yosys - make manual - make install - - - update pdf files on the website - - cd ~yosys-web - make update_cmd - make update_show - git commit -am update - make push - - -In master branch: - - git merge {release-tag} - - set version to x.y.z+ in Makefile - - add section "Yosys x.y.z .. x.y.z+" to CHANGELOG - 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/CodingReadme b/CodingReadme new file mode 100644 index 000000000..8f515e1f4 --- /dev/null +++ b/CodingReadme @@ -0,0 +1,194 @@ + + +Getting Started +=============== + + +Reading List +------------ + +To write Yosys C++ code you need to know at least the following classes in kernel/rtlil.h: + + 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: + + cd ~yosys + gitk & + vi CHANGELOG + + +Run all tests with "make config-{clang-debug,gcc-debug,gcc-4.6,release}": + + cd ~yosys + make clean + make test vloghtb + make install + + cd ~yosys-bigsim + make clean + make full + + cd ~vloghammer + make purge + make gen_issues gen_samples + make SYN_LIST="yosys" SIM_LIST="icarus yosim verilator" FULL=1 world + chromium-browser report.html + + +Then with default config setting: + + cd ~yosys + ./yosys -p 'proc; show' tests/simple/fiedler-cooley.v + ./yosys -p 'proc; opt; show' tests/simple/fiedler-cooley.v + + cd ~yosys + make manual + - sanity check the figures in the appnotes and presentation + - if there are any odd things -> investigate + - make cosmetic changes to the .tex files if necessary + + +Also with default config setting: + + cd ~yosys/techlibs/cmos + bash testbench.sh + + cd ~yosys/techlibs/xilinx/example_sim_counter + bash run_sim.sh + + cd ~yosys/techlibs/xilinx/example_mojo_counter + bash example.sh + + +Finally if a current verific library is available: + + cd ~yosys + cat frontends/verific/build_amd64.txt + - follow instructions + + cd frontends/verific + ../../yosys test_navre.ys + + +Release candiate: + + - create branch yosys-x.y.z-rc and push to github + - contact the usual suspects per mail and ask them to test + - post on the reddit and ask people to test + - commit KISS fixes to the -rc branch if necessary + + +Release: + + - set YOSYS_VER to x.y.z in Makefile + - update version string in CHANGELOG + git commit -am "Yosys x.y.z" + + - push tag to github + - post changelog on github + - post short release note on reddit + - delete -rc branch from github + + +Updating the website: + + cd ~yosys + make manual + make install + + - update pdf files on the website + + cd ~yosys-web + make update_cmd + make update_show + git commit -am update + make push + + +In master branch: + + git merge {release-tag} + - set version to x.y.z+ in Makefile + - add section "Yosys x.y.z .. x.y.z+" to CHANGELOG + git commit --amend -am "Yosys x.y.z+" + + 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