riscv
/
yosys
mirror of https://github.com/YosysHQ/yosys.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

split CodingReadme into multiple files

This commit is contained in:
N. Engelhardt 2021-03-22 19:16:25 +01:00
parent 92d5550a90
commit d9ec35a526
11 changed files with 295 additions and 318 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.clang-format
View File

@ -6,7 +6,7 @@ BreakBeforeBraces: Linux
AllowShortIfStatementsOnASingleLine: false AllowShortIfStatementsOnASingleLine: false
IndentCaseLabels: false IndentCaseLabels: false
# From CodingReadme # From guidelines/CodingStyle
TabWidth: 8 TabWidth: 8
ContinuationIndentWidth: 2 ContinuationIndentWidth: 2
ColumnLimit: 150 ColumnLimit: 150

3
.dockerignore
View File

@ -6,8 +6,7 @@
Dockerfile Dockerfile
README.md README.md
manual manual
CodingReadme guidelines
CodeOfConduct CodeOfConduct
.travis .travis
.travis.yml .travis.yml

2
README.md
View File

@ -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: including a manual that even describes some of the Yosys internals:
- http://www.clifford.at/yosys/documentation.html - 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. for people interested in using the Yosys C++ APIs.
Users interested in formal verification might want to use the formal verification Users interested in formal verification might want to use the formal verification

120
guidelines/Checklists Normal file
View File

@ -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

0
CodeOfConduct → guidelines/CodeOfConduct
View File

35
guidelines/CodingStyle Normal file
View File

@ -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.

309
CodingReadme → guidelines/GettingStarted
View File

@ -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 Getting Started
=============== ===============
@ -253,304 +246,4 @@ Notes on the existing codebase
For historical reasons not all parts of Yosys adhere to the current coding 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 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. 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
```

69
guidelines/UnitTests Normal file
View File

@ -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
```

60
guidelines/Windows Normal file
View File

@ -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

2
kernel/yosys.h
View File

@ -33,7 +33,7 @@
// This header is very boring. It just defines some general things that // This header is very boring. It just defines some general things that
// belong nowhere else and includes the interesting headers. // 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 #ifndef YOSYS_H

11
manual/CHAPTER_Prog.tex
View File

@ -5,13 +5,15 @@
This chapter contains some bits and pieces of information about programming This chapter contains some bits and pieces of information about programming
yosys extensions. Also consult the section on programming in the ``Yosys yosys extensions. Also consult the section on programming in the ``Yosys
Presentation'' (can be downloaded from the Yosys website as PDF) and don't 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} \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=Makefile,numbers=left,frame=single,language=make]{CHAPTER_Prog/Makefile}
\lstinputlisting[title=test.v,numbers=left,frame=single,language=Verilog]{CHAPTER_Prog/test.v} \lstinputlisting[title=test.v,numbers=left,frame=single,language=Verilog]{CHAPTER_Prog/test.v}