mirrors/yosys
3
0
Fork 0
mirror of https://github.com/YosysHQ/yosys synced 2025-04-25 10:05:33 +00:00
Code Activity

Goodbye guidelines (except GettingStarted)

Browse source 
Drop the parts that are being dropped.
Move the things that are being moved.
Also move the verilog stuff out of README and into the docs.
GettingStarted is less cut and dry, so hold off on that one.
This commit is contained in:
Krystine Sherwin 2024-12-05 09:21:12 +13:00
parent f0da1cc67f
commit 9925b27432
No known key found for this signature in database
11 changed files with 532 additions and 711 deletions
Download patch file Download diff file Expand all files Collapse all files

116
guidelines/Checklists
View file

@ -1,116 +0,0 @@
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 docs/source/CHAPTER_CellLib.rst (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 docs
- sanity check the figures in docs/images
- if there are any odd things -> investigate
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}":
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 install
cd ~yosys-web
make update_show
git commit -am update
make push
- Read the Docs updates handled by Jenkins on source change

72
guidelines/CodeOfConduct
View file

@ -1,72 +0,0 @@
Contributor Covenant Code of Conduct
Our Pledge
In the interest of fostering an open and welcoming environment, we as
contributors and maintainers pledge to making participation in our project and
our community a harassment-free experience for everyone, regardless of age, body
size, disability, ethnicity, gender identity and expression, level of experience,
nationality, personal appearance, race, religion, or sexual identity and
orientation.
Our Standards
Examples of behavior that contributes to creating a positive environment
include:
* Using welcoming and inclusive language
* Being respectful of differing viewpoints and experiences
* Gracefully accepting constructive criticism
* Focusing on what is best for the community
* Showing empathy towards other community members
Examples of unacceptable behavior by participants include:
* The use of sexualized language or imagery and unwelcome sexual attention or
advances
* Trolling, insulting/derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or electronic
address, without explicit permission
* Other conduct which could reasonably be considered inappropriate in a
professional setting
Our Responsibilities
Project maintainers are responsible for clarifying the standards of acceptable
behavior and are expected to take appropriate and fair corrective action in
response to any instances of unacceptable behavior.
Project maintainers have the right and responsibility to remove, edit, or
reject comments, commits, code, wiki edits, issues, and other contributions
that are not aligned to this Code of Conduct, or to ban temporarily or
permanently any contributor for other behaviors that they deem inappropriate,
threatening, offensive, or harmful.
Scope
This Code of Conduct applies both within project spaces and in public spaces
when an individual is representing the project or its community. Examples of
representing a project or community include using an official project e-mail
address, posting via an official social media account, or acting as an appointed
representative at an online or offline event. Representation of a project may be
further defined and clarified by project maintainers.
Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported by contacting the project team at contact@yosyshq.com and/or
claire@clairexen.net. All complaints will be reviewed and investigated and
will result in a response that is deemed necessary and appropriate to the
circumstances. The project team is obligated to maintain confidentiality with
regard to the reporter of an incident. Further details of specific enforcement
policies may be posted separately.
Project maintainers who do not follow or enforce the Code of Conduct in good
faith may face temporary or permanent repercussions as determined by other
members of the project's leadership.
Attribution
This Code of Conduct is adapted from the Contributor Covenant, version 1.4,
available at http://contributor-covenant.org/version/1/4/

34
guidelines/CodingStyle
View file

@ -1,34 +0,0 @@
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/process/coding-style.rst
C++ Language
-------------
Yosys is written in C++17.
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.

69
guidelines/UnitTests
View file

@ -1,69 +0,0 @@
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
```

83
guidelines/Windows
View file

@ -1,83 +0,0 @@
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
Compiling with Visual Studio
============================
Visual Studio builds are not directly supported by build scripts, but they are still possible.
1. Easy way
- Go to https://github.com/YosysHQ/yosys/actions/workflows/vs.yml?query=branch%3Amain
- Click on the most recent completed run
- In Artifacts region find vcxsrc and click on it to download
- Unpack downloaded ZIP file
- Open YosysVS.sln with Visual Studio
2. Using WSL or MSYS2
- Make sure to have make, python3 and git available
- Git clone yosys repository
- Execute ```make vcxsrc YOSYS_VER=latest```
- File yosys-win32-vcxsrc-latest.zip will be created
- Transfer that file to location visible by Windows application
- Unpack ZIP
- Open YosysVS.sln with Visual Studio
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/YosysHQ/yosys.git yosys-win32
cd yosys-win32
make config-mxe
make -j$(nproc) mxebin