diff options
| -rw-r--r-- | .clang-format | 2 | ||||
| -rw-r--r-- | .dockerignore | 3 | ||||
| -rw-r--r-- | README.md | 2 | ||||
| -rw-r--r-- | guidelines/Checklists | 120 | ||||
| -rw-r--r-- | guidelines/CodeOfConduct (renamed from CodeOfConduct) | 0 | ||||
| -rw-r--r-- | guidelines/CodingStyle | 35 | ||||
| -rw-r--r-- | guidelines/GettingStarted (renamed from CodingReadme) | 309 | ||||
| -rw-r--r-- | guidelines/UnitTests | 69 | ||||
| -rw-r--r-- | guidelines/Windows | 60 | ||||
| -rw-r--r-- | kernel/yosys.h | 2 | ||||
| -rw-r--r-- | manual/CHAPTER_Prog.tex | 11 |
11 files changed, 295 insertions, 318 deletions
diff --git a/.clang-format b/.clang-format index 28d13da25..c86fa8c1c 100644 --- a/.clang-format +++ b/.clang-format @@ -6,7 +6,7 @@ BreakBeforeBraces: Linux AllowShortIfStatementsOnASingleLine: false IndentCaseLabels: false -# From CodingReadme +# From guidelines/CodingStyle TabWidth: 8 ContinuationIndentWidth: 2 ColumnLimit: 150 diff --git a/.dockerignore b/.dockerignore index 9910e9954..9f1da94da 100644 --- a/.dockerignore +++ b/.dockerignore @@ -6,8 +6,7 @@ Dockerfile
README.md
manual
-CodingReadme
+guidelines
CodeOfConduct
.travis
.travis.yml
-
@@ -44,7 +44,7 @@ The "Documentation" page on the web site contains links to more resources, including a manual that even describes some of the Yosys internals: - http://www.clifford.at/yosys/documentation.html -The file `CodingReadme` in this directory contains additional information +The directory `guidelines` contains additional information for people interested in using the Yosys C++ APIs. Users interested in formal verification might want to use the formal verification diff --git a/guidelines/Checklists b/guidelines/Checklists new file mode 100644 index 000000000..cc61c7876 --- /dev/null +++ b/guidelines/Checklists @@ -0,0 +1,120 @@ +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 + + +Update and check documentation: + + cd ~yosys + make update-manual + 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 + + cd ~yosys + vi README guidelines/* + - is the information provided in those file still up to date + + +Then with default config setting: + + cd ~yosys + make vgtest + + cd ~yosys + ./yosys -p 'proc; show' tests/simple/fiedler-cooley.v + ./yosys -p 'proc; opt; show' tests/simple/fiedler-cooley.v + ./yosys -p 'synth; show' tests/simple/fiedler-cooley.v + ./yosys -p 'synth_xilinx -top up3down5; show' tests/simple/fiedler-cooley.v + + cd ~yosys/examples/cmos + bash testbench.sh + + cd ~yosys/examples/basys3 + bash run.sh + + +Test building plugins with various of the standard passes: + + yosys-config --build test.so equiv_simple.cc + - also check the code examples in guidelines/GettingStarted + + +And if a version of the verific library is currently available: + + cd ~yosys + cat frontends/verific/build_amd64.txt + - follow instructions + + cd frontends/verific + ../../yosys test_navre.ys + + +Finally run all tests with "make config-{clang,gcc,gcc-4.8}": + + cd ~yosys + make clean + make test + make ystests + make vloghtb + make install + + cd ~yosys-bigsim + make clean + make full + + cd ~vloghammer + make purge gen_issues gen_samples + make SYN_LIST="yosys" SIM_LIST="icarus yosim verilator" REPORT_FULL=1 world + chromium-browser report.html + + +Release: + + - set YOSYS_VER to x.y.z in Makefile + - remove "bumpversion" target from 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 + + +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 diff --git a/CodeOfConduct b/guidelines/CodeOfConduct index 4f779977b..4f779977b 100644 --- a/CodeOfConduct +++ b/guidelines/CodeOfConduct diff --git a/guidelines/CodingStyle b/guidelines/CodingStyle new file mode 100644 index 000000000..d3d3a7134 --- /dev/null +++ b/guidelines/CodingStyle @@ -0,0 +1,35 @@ +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 Style: + https://www.kernel.org/doc/Documentation/CodingStyle + + +C++ Language +------------- + +Yosys is written in C++11. At the moment only constructs supported by +gcc 4.8 are 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 "GetSize(foobar)" instead +of "foobar.size()". (GetSize() is defined in kernel/yosys.h) + +Use range-based for loops whenever applicable.
\ No newline at end of file diff --git a/CodingReadme b/guidelines/GettingStarted index 7d4ded93d..fcc84c153 100644 --- a/CodingReadme +++ b/guidelines/GettingStarted @@ -1,10 +1,3 @@ - -This file contains some very brief documentation on things like programming APIs. -Also consult the Yosys manual and the section about programming in the presentation. -(Both can be downloaded as PDF from the yosys webpage.) - - ---snip-- only the lines below this mark are included in the yosys manual --snip-- Getting Started =============== @@ -253,304 +246,4 @@ Notes on the existing codebase For historical reasons not all parts of Yosys adhere to the current coding style. 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 Style: - https://www.kernel.org/doc/Documentation/CodingStyle - - -C++ Language -------------- - -Yosys is written in C++11. At the moment only constructs supported by -gcc 4.8 are 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 "GetSize(foobar)" instead -of "foobar.size()". (GetSize() is defined in kernel/yosys.h) - -Use range-based for loops whenever applicable. - - ---snap-- only the lines above this mark are included in the yosys manual --snap-- - - -Creating the Visual Studio Template Project -=========================================== - -1. Create an empty Visual C++ Win32 Console App project - - Microsoft Visual Studio Express 2013 for Windows Desktop - Open New Project Wizard (File -> New Project..) - - Project Name: YosysVS - Solution Name: YosysVS - [X] Create directory for solution - [ ] Add to source control - - [X] Console applications - [X] Empty Project - [ ] SDL checks - -2. Open YosysVS Project Properties - - Select Configuration: All Configurations - - C/C++ -> General -> Additional Include Directories - Add: ..\yosys - - C/C++ -> Preprocessor -> Preprocessor Definitions - Add: _YOSYS_;_CRT_SECURE_NO_WARNINGS - -3. Resulting file system tree: - - YosysVS/ - YosysVS/YosysVS - YosysVS/YosysVS/YosysVS.vcxproj - YosysVS/YosysVS/YosysVS.vcxproj.filters - YosysVS/YosysVS.sdf - YosysVS/YosysVS.sln - YosysVS/YosysVS.v12.suo - -4. Zip YosysVS as YosysVS-Tpl-v1.zip - - - -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 - - -Update and check documentation: - - cd ~yosys - make update-manual - 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 - - cd ~yosys - vi README CodingReadme - - is the information provided in those file still up to date - - -Then with default config setting: - - cd ~yosys - make vgtest - - cd ~yosys - ./yosys -p 'proc; show' tests/simple/fiedler-cooley.v - ./yosys -p 'proc; opt; show' tests/simple/fiedler-cooley.v - ./yosys -p 'synth; show' tests/simple/fiedler-cooley.v - ./yosys -p 'synth_xilinx -top up3down5; show' tests/simple/fiedler-cooley.v - - cd ~yosys/examples/cmos - bash testbench.sh - - cd ~yosys/examples/basys3 - bash run.sh - - -Test building plugins with various of the standard passes: - - yosys-config --build test.so equiv_simple.cc - - also check the code examples in CodingReadme - - -And if a version of the verific library is currently available: - - cd ~yosys - cat frontends/verific/build_amd64.txt - - follow instructions - - cd frontends/verific - ../../yosys test_navre.ys - - -Finally run all tests with "make config-{clang,gcc,gcc-4.8}": - - cd ~yosys - make clean - make test - make ystests - make vloghtb - make install - - cd ~yosys-bigsim - make clean - make full - - cd ~vloghammer - make purge gen_issues gen_samples - make SYN_LIST="yosys" SIM_LIST="icarus yosim verilator" REPORT_FULL=1 world - chromium-browser report.html - - -Release: - - - set YOSYS_VER to x.y.z in Makefile - - remove "bumpversion" target from 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 - - -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 - - - -Cross-Building for Windows with MXE -=================================== - -Check http://mxe.cc/#requirements and install all missing requirements. - -As root (or other user with write access to /usr/local/src): - - cd /usr/local/src - git clone https://github.com/mxe/mxe.git - cd mxe - - make -j$(nproc) MXE_PLUGIN_DIRS="plugins/tcl.tk" \ - MXE_TARGETS="i686-w64-mingw32.static" \ - gcc tcl readline - -Then as regular user in some directory where you build stuff: - - git clone https://github.com/cliffordwolf/yosys.git yosys-win32 - cd yosys-win32 - make config-mxe - make -j$(nproc) mxebin - - - -How to add unit test -==================== - -Unit test brings some advantages, briefly, we can list some of them (reference -[1](https://en.wikipedia.org/wiki/Unit_testing)): - -* Tests reduce bugs in new features; -* Tests reduce bugs in existing features; -* Tests are good documentation; -* Tests reduce the cost of change; -* Tests allow refactoring; - -With those advantages in mind, it was required to choose a framework which fits -well with C/C++ code. Hence, it was chosen (google test) -[https://github.com/google/googletest], because it is largely used and it is -relatively easy learn. - -Install and configure google test (manually) --------------------------------------------- - -In this section, you will see a brief description of how to install google -test. However, it is strongly recommended that you take a look to the official -repository (https://github.com/google/googletest) and refers to that if you -have any problem to install it. Follow the steps below: - -* Install: cmake and pthread -* Clone google test project from: https://github.com/google/googletest and - enter in the project directory -* Inside project directory, type: - -``` -cmake -DBUILD_SHARED_LIBS=ON . -make -``` - -* After compilation, copy all "*.so" inside directory "googlemock" and - "googlemock/gtest" to "/usr/lib/" -* Done! Now you can compile your tests. - -If you have any problem, go to the official repository to find help. - -Ps.: Some distros already have googletest packed. If your distro supports it, -you can use it instead of compile. - -Create new unit test --------------------- - -If you want to add new unit tests for Yosys, just follow the steps below: - -* Go to directory "yosys/test/unit/" -* In this directory you can find something similar Yosys's directory structure. - To create your unit test file you have to follow this pattern: - fileNameToImplementUnitTest + Test.cc. E.g.: if you want to implement the - unit test for kernel/celledges.cc, you will need to create a file like this: - tests/unit/kernel/celledgesTest.cc; -* Implement your unit test - -Run unit test -------------- - -To compile and run all unit tests, just go to yosys root directory and type: -``` -make unit-test -``` - -If you want to remove all unit test files, type: -``` -make clean-unit-test -``` +for the new code instead of trying to mimic the style of the surrounding code.
\ No newline at end of file diff --git a/guidelines/UnitTests b/guidelines/UnitTests new file mode 100644 index 000000000..d42a63ce5 --- /dev/null +++ b/guidelines/UnitTests @@ -0,0 +1,69 @@ +How to add unit test +==================== + +Unit test brings some advantages, briefly, we can list some of them (reference +[1](https://en.wikipedia.org/wiki/Unit_testing)): + +* Tests reduce bugs in new features; +* Tests reduce bugs in existing features; +* Tests are good documentation; +* Tests reduce the cost of change; +* Tests allow refactoring; + +With those advantages in mind, it was required to choose a framework which fits +well with C/C++ code. Hence, it was chosen (google test) +[https://github.com/google/googletest], because it is largely used and it is +relatively easy learn. + +Install and configure google test (manually) +-------------------------------------------- + +In this section, you will see a brief description of how to install google +test. However, it is strongly recommended that you take a look to the official +repository (https://github.com/google/googletest) and refers to that if you +have any problem to install it. Follow the steps below: + +* Install: cmake and pthread +* Clone google test project from: https://github.com/google/googletest and + enter in the project directory +* Inside project directory, type: + +``` +cmake -DBUILD_SHARED_LIBS=ON . +make +``` + +* After compilation, copy all "*.so" inside directory "googlemock" and + "googlemock/gtest" to "/usr/lib/" +* Done! Now you can compile your tests. + +If you have any problem, go to the official repository to find help. + +Ps.: Some distros already have googletest packed. If your distro supports it, +you can use it instead of compile. + +Create new unit test +-------------------- + +If you want to add new unit tests for Yosys, just follow the steps below: + +* Go to directory "yosys/test/unit/" +* In this directory you can find something similar Yosys's directory structure. + To create your unit test file you have to follow this pattern: + fileNameToImplementUnitTest + Test.cc. E.g.: if you want to implement the + unit test for kernel/celledges.cc, you will need to create a file like this: + tests/unit/kernel/celledgesTest.cc; +* Implement your unit test + +Run unit test +------------- + +To compile and run all unit tests, just go to yosys root directory and type: +``` +make unit-test +``` + +If you want to remove all unit test files, type: +``` +make clean-unit-test +``` diff --git a/guidelines/Windows b/guidelines/Windows new file mode 100644 index 000000000..3bd86f3ec --- /dev/null +++ b/guidelines/Windows @@ -0,0 +1,60 @@ +Creating the Visual Studio Template Project +=========================================== + +1. Create an empty Visual C++ Win32 Console App project + + Microsoft Visual Studio Express 2013 for Windows Desktop + Open New Project Wizard (File -> New Project..) + + Project Name: YosysVS + Solution Name: YosysVS + [X] Create directory for solution + [ ] Add to source control + + [X] Console applications + [X] Empty Project + [ ] SDL checks + +2. Open YosysVS Project Properties + + Select Configuration: All Configurations + + C/C++ -> General -> Additional Include Directories + Add: ..\yosys + + C/C++ -> Preprocessor -> Preprocessor Definitions + Add: _YOSYS_;_CRT_SECURE_NO_WARNINGS + +3. Resulting file system tree: + + YosysVS/ + YosysVS/YosysVS + YosysVS/YosysVS/YosysVS.vcxproj + YosysVS/YosysVS/YosysVS.vcxproj.filters + YosysVS/YosysVS.sdf + YosysVS/YosysVS.sln + YosysVS/YosysVS.v12.suo + +4. Zip YosysVS as YosysVS-Tpl-v1.zip + +Cross-Building for Windows with MXE +=================================== + +Check http://mxe.cc/#requirements and install all missing requirements. + +As root (or other user with write access to /usr/local/src): + + cd /usr/local/src + git clone https://github.com/mxe/mxe.git + cd mxe + + make -j$(nproc) MXE_PLUGIN_DIRS="plugins/tcl.tk" \ + MXE_TARGETS="i686-w64-mingw32.static" \ + gcc tcl readline + +Then as regular user in some directory where you build stuff: + + git clone https://github.com/cliffordwolf/yosys.git yosys-win32 + cd yosys-win32 + make config-mxe + make -j$(nproc) mxebin
\ No newline at end of file diff --git a/kernel/yosys.h b/kernel/yosys.h index 43aecdbc8..e93d09cd4 100644 --- a/kernel/yosys.h +++ b/kernel/yosys.h @@ -33,7 +33,7 @@ // 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. +// Find more information in the "guidelines/GettingStarted" file. #ifndef YOSYS_H diff --git a/manual/CHAPTER_Prog.tex b/manual/CHAPTER_Prog.tex index 3cbc95a19..49432f73b 100644 --- a/manual/CHAPTER_Prog.tex +++ b/manual/CHAPTER_Prog.tex @@ -5,13 +5,15 @@ This chapter contains some bits and pieces of information about programming yosys extensions. Also consult the section on programming in the ``Yosys Presentation'' (can be downloaded from the Yosys website as PDF) and don't -be afraid to ask questions on the Yosys Subreddit. +be afraid to ask questions on the YosysHQ Slack. -\section{The ``CodingReadme'' File} +\section{Guidelines} -The following is an excerpt of the {\tt CodingReadme} file from the Yosys source tree. +The {\tt guidelines} directory contains notes on various aspects of Yosys development. The files {\tt GettingStarted} and {\tt CodingStyle} may be of particular interest, and are reproduced here. -\lstinputlisting[title=CodingReadme,rangeprefix=--,rangesuffix=--,includerangemarker=false,linerange=snip-snap,numbers=left,frame=single]{../CodingReadme} +\lstinputlisting[title=GettingStarted,numbers=left,frame=single]{../guidelines/GettingStarted} + +\lstinputlisting[title=CodingStyle,numbers=left,frame=single]{../guidelines/CodingStyle} \section{The ``stubsnets'' Example Module} @@ -23,4 +25,3 @@ The following is the complete code of the ``stubsnets'' example module. It is in \lstinputlisting[title=Makefile,numbers=left,frame=single,language=make]{CHAPTER_Prog/Makefile} \lstinputlisting[title=test.v,numbers=left,frame=single,language=Verilog]{CHAPTER_Prog/test.v} - |