From d9ec35a526b9583727ef484ec68bc288dcddb0c8 Mon Sep 17 00:00:00 2001 From: "N. Engelhardt" Date: Mon, 22 Mar 2021 19:16:25 +0100 Subject: split CodingReadme into multiple files --- guidelines/Checklists | 120 ++++++++++++++++++++++ guidelines/CodeOfConduct | 73 ++++++++++++++ guidelines/CodingStyle | 35 +++++++ guidelines/GettingStarted | 249 ++++++++++++++++++++++++++++++++++++++++++++++ guidelines/UnitTests | 69 +++++++++++++ guidelines/Windows | 60 +++++++++++ 6 files changed, 606 insertions(+) create mode 100644 guidelines/Checklists create mode 100644 guidelines/CodeOfConduct create mode 100644 guidelines/CodingStyle create mode 100644 guidelines/GettingStarted create mode 100644 guidelines/UnitTests create mode 100644 guidelines/Windows (limited to 'guidelines') 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/guidelines/CodeOfConduct b/guidelines/CodeOfConduct new file mode 100644 index 000000000..4f779977b --- /dev/null +++ b/guidelines/CodeOfConduct @@ -0,0 +1,73 @@ +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 clifford@clifford.at (and/or +cliffordvienna@gmail.com if you think your mail to the other address got +stuck in the spam filter). 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/ 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/guidelines/GettingStarted b/guidelines/GettingStarted new file mode 100644 index 000000000..fcc84c153 --- /dev/null +++ b/guidelines/GettingStarted @@ -0,0 +1,249 @@ +Getting Started +=============== + + +Outline of a Yosys command +-------------------------- + +Here is a the C++ code for a "hello_world" Yosys command (hello.cc): + + #include "kernel/yosys.h" + + USING_YOSYS_NAMESPACE + PRIVATE_NAMESPACE_BEGIN + + struct HelloWorldPass : public Pass { + HelloWorldPass() : Pass("hello_world") { } + void execute(vector, Design*) override { + log("Hello World!\n"); + } + } HelloWorldPass; + + PRIVATE_NAMESPACE_END + +This can be built into a Yosys module using the following command: + + yosys-config --exec --cxx --cxxflags --ldflags -o hello.so -shared hello.cc --ldlibs + +Or short: + + yosys-config --build hello.so hello.cc + +And then executed using the following command: + + yosys -m hello.so -p hello_world + + +Yosys Data Structures +--------------------- + +Here is a short list of data structures that you should make yourself familiar +with before you write C++ code for Yosys. The following data structures are all +defined when "kernel/yosys.h" is included and USING_YOSYS_NAMESPACE is used. + + 1. Yosys Container Classes + +Yosys uses dict and pool as main container classes. dict is +essentially a replacement for std::unordered_map and pool is a +replacement for std::unordered_set. The main characteristics are: + + - dict and pool are about 2x faster than the std containers + + - references to elements in a dict or pool are invalidated by + insert and remove operations (similar to std::vector on push_back()). + + - some iterators are invalidated by erase(). specifically, iterators + that have not passed the erased element yet are invalidated. (erase() + itself returns valid iterator to the next element.) + + - no iterators are invalidated by insert(). elements are inserted at + begin(). i.e. only a new iterator that starts at begin() will see the + inserted elements. + + - the method .count(key, iterator) is like .count(key) but only + considers elements that can be reached via the iterator. + + - iterators can be compared. it1 < it2 means that the position of t2 + can be reached via t1 but not vice versa. + + - the method .sort() can be used to sort the elements in the container + the container stays sorted until elements are added or removed. + + - dict and pool will have the same order of iteration across + all compilers, standard libraries and architectures. + +In addition to dict and pool there is also an idict that +creates a bijective map from K to the integers. For example: + + idict si; + log("%d\n", si("hello")); // will print 42 + log("%d\n", si("world")); // will print 43 + log("%d\n", si.at("world")); // will print 43 + log("%d\n", si.at("dummy")); // will throw exception + log("%s\n", si[42].c_str())); // will print hello + log("%s\n", si[43].c_str())); // will print world + log("%s\n", si[44].c_str())); // will throw exception + +It is not possible to remove elements from an idict. + +Finally mfp implements a merge-find set data structure (aka. disjoint-set or +union-find) over the type K ("mfp" = merge-find-promote). + + 2. Standard STL data types + +In Yosys we use std::vector and std::string whenever applicable. When +dict and pool are not suitable then std::map and std::set +are used instead. + +The types std::vector and std::string are also available as vector +and string in the Yosys namespace. + + 3. RTLIL objects + +The current design (essentially a collection of modules, each defined by a +netlist) is stored in memory using RTLIL object (declared in kernel/rtlil.h, +automatically included by kernel/yosys.h). You should glance over at least +the declarations for the following types in kernel/rtlil.h: + + RTLIL::IdString + This is a handle for an identifier (e.g. cell or wire name). + It feels a lot like a std::string, but is only a single int + in size. (The actual string is stored in a global lookup + table.) + + RTLIL::SigBit + A single signal bit. I.e. either a constant state (0, 1, + x, z) or a single bit from a wire. + + RTLIL::SigSpec + Essentially a vector of SigBits. + + RTLIL::Wire + RTLIL::Cell + The building blocks of the netlist in a module. + + RTLIL::Module + RTLIL::Design + The module is a container with connected cells and wires + in it. The design is a container with modules in it. + +All this types are also available without the RTLIL:: prefix in the Yosys +namespace. + + 4. SigMap and other Helper Classes + +There are a couple of additional helper classes that are in wide use +in Yosys. Most importantly there is SigMap (declared in kernel/sigtools.h). + +When a design has many wires in it that are connected to each other, then a +single signal bit can have multiple valid names. The SigMap object can be used +to map SigSpecs or SigBits to unique SigSpecs and SigBits that consistently +only use one wire from such a group of connected wires. For example: + + SigBit a = module->addWire(NEW_ID); + SigBit b = module->addWire(NEW_ID); + module->connect(a, b); + + log("%d\n", a == b); // will print 0 + + SigMap sigmap(module); + log("%d\n", sigmap(a) == sigmap(b)); // will print 1 + + +Using the RTLIL Netlist Format +------------------------------ + +In the RTLIL netlist format the cell ports contain SigSpecs that point to the +Wires. There are no references in the other direction. This has two direct +consequences: + +(1) It is very easy to go from cells to wires but hard to go in the other way. + +(2) There is no danger in removing cells from the netlists, but removing wires +can break the netlist format when there are still references to the wire +somewhere in the netlist. + +The solution to (1) is easy: Create custom indexes that allow you to make fast +lookups for the wire-to-cell direction. You can either use existing generic +index structures to do that (such as the ModIndex class) or write your own +index. For many application it is simplest to construct a custom index. For +example: + + SigMap sigmap(module); + dict sigbit_to_driver_index; + + for (auto cell : module->cells()) + for (auto &conn : cell->connections()) + if (cell->output(conn.first)) + for (auto bit : sigmap(conn.second)) + sigbit_to_driver_index[bit] = cell; + +Regarding (2): There is a general theme in Yosys that you don't remove wires +from the design. You can rename them, unconnect them, but you do not actually remove +the Wire object from the module. Instead you let the "clean" command take care +of the dangling wires. On the other hand it is safe to remove cells (as long as +you make sure this does not invalidate a custom index you are using in your code). + + +Example Code +------------ + +The following yosys commands are a good starting point if you are looking for examples +of how to use the Yosys API: + + manual/CHAPTER_Prog/stubnets.cc + manual/PRESENTATION_Prog/my_cmd.cc + + +Script Passes +------------- + +The ScriptPass base class can be used to implement passes that just call other passes, +like a script. Examples for such passes are: + + techlibs/common/prep.cc + techlibs/common/synth.cc + +In some cases it is easier to implement such a pass as regular pass, for example when +ScriptPass doesn't provide the type of flow control desired. (But many of the +script passes in Yosys that don't use ScriptPass simply predate the ScriptPass base +class.) Examples for such passes are: + + passes/opt/opt.cc + passes/proc/proc.cc + +Whether they use the ScriptPass base-class or not, a pass should always either +call other passes without doing any non-trivial work itself, or should implement +a non-trivial algorithm but not call any other passes. The reason for this is that +this helps containing complexity in individual passes and simplifies debugging the +entire system. + +Exceptions to this rule should be rare and limited to cases where calling other +passes is optional and only happens when requested by the user (such as for +example `techmap -autoproc`), or where it is about commands that are "top-level +commands" in their own right, not components to be used in regular synthesis +flows (such as the `bugpoint` command). + +A pass that would "naturally" call other passes and also do some work itself +should be re-written in one of two ways: + +1) It could be re-written as script pass with the parts that are not calls +to other passes factored out into individual new passes. Usually in those +cases the new sub passes share the same prefix as the top-level script pass. + +2) It could be re-written so that it already expects the design in a certain +state, expecting the calling script to set up this state before calling the +pass in questions. + +Many back-ends are examples for the 2nd approach. For example, `write_aiger` +does not convert the design into AIG representation, but expects the design +to be already in this form, and prints an `Unsupported cell type` error +message otherwise. + + +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. \ 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 -- cgit v1.2.3 From 72787f52fc31954e4b7dc3dc34d86705fc4e9dd1 Mon Sep 17 00:00:00 2001 From: Claire Xenia Wolf Date: Tue, 8 Jun 2021 00:39:36 +0200 Subject: Fixing old e-mail addresses and deadnames s/((Claire|Xen|Xenia|Clifford)\s+)+(Wolf|Xen)\s+<(claire|clifford)@(symbioticeda.com|clifford.at|yosyshq.com)>/Claire Xenia Wolf /gi; s/((Nina|Nak|N\.)\s+)+Engelhardt\s+/N. Engelhardt /gi; s/((David)\s+)+Shah\s+<(dave|david)@(symbioticeda.com|yosyshq.com|ds0.me)>/David Shah /gi; s/((Miodrag)\s+)+Milanovic\s+<(miodrag|micko)@(symbioticeda.com|yosyshq.com)>/Miodrag Milanovic /gi; s,https?://www.clifford.at/yosys/,http://yosyshq.net/yosys/,g; --- guidelines/CodeOfConduct | 5 ++--- guidelines/Windows | 4 ++-- 2 files changed, 4 insertions(+), 5 deletions(-) (limited to 'guidelines') diff --git a/guidelines/CodeOfConduct b/guidelines/CodeOfConduct index 4f779977b..92decd3b6 100644 --- a/guidelines/CodeOfConduct +++ b/guidelines/CodeOfConduct @@ -55,9 +55,8 @@ 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 clifford@clifford.at (and/or -cliffordvienna@gmail.com if you think your mail to the other address got -stuck in the spam filter). All complaints will be reviewed and investigated and +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 diff --git a/guidelines/Windows b/guidelines/Windows index 3bd86f3ec..16ba57c9d 100644 --- a/guidelines/Windows +++ b/guidelines/Windows @@ -54,7 +54,7 @@ As root (or other user with write access to /usr/local/src): Then as regular user in some directory where you build stuff: - git clone https://github.com/cliffordwolf/yosys.git yosys-win32 + git clone https://github.com/YosysHQ/yosys.git yosys-win32 cd yosys-win32 make config-mxe - make -j$(nproc) mxebin \ No newline at end of file + make -j$(nproc) mxebin -- cgit v1.2.3 From 41e215219bf2b8fd9ec8df15229fb8dabfd5b53f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miodrag=20Milanovi=C4=87?= Date: Mon, 17 Jan 2022 10:07:56 +0100 Subject: Add info about VS build --- guidelines/Windows | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) (limited to 'guidelines') diff --git a/guidelines/Windows b/guidelines/Windows index 16ba57c9d..6cb91406c 100644 --- a/guidelines/Windows +++ b/guidelines/Windows @@ -37,6 +37,29 @@ Creating the Visual Studio Template Project 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%3Amaster + - Click on first item + - 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 =================================== -- cgit v1.2.3 From 703306c119e3dcb6cca353634e0babe82be1cb2a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miodrag=20Milanovi=C4=87?= Date: Mon, 17 Jan 2022 13:11:15 +0100 Subject: Update guidelines/Windows Co-authored-by: N. Engelhardt --- guidelines/Windows | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'guidelines') diff --git a/guidelines/Windows b/guidelines/Windows index 6cb91406c..2af0620fa 100644 --- a/guidelines/Windows +++ b/guidelines/Windows @@ -45,7 +45,7 @@ Visual Studio builds are not directly supported by build scripts, but they are s 1. Easy way - Go to https://github.com/YosysHQ/yosys/actions/workflows/vs.yml?query=branch%3Amaster - - Click on first item + - 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 -- cgit v1.2.3