From: N. Engelhardt Date: Mon, 22 Mar 2021 18:16:25 +0000 (+0100) Subject: split CodingReadme into multiple files X-Git-Tag: yosys-0.10~234^2 X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=d9ec35a526b9583727ef484ec68bc288dcddb0c8;p=yosys.git split CodingReadme into multiple files --- 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 - diff --git a/CodeOfConduct b/CodeOfConduct deleted file mode 100644 index 4f779977b..000000000 --- a/CodeOfConduct +++ /dev/null @@ -1,73 +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 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/CodingReadme b/CodingReadme deleted file mode 100644 index 7d4ded93d..000000000 --- a/CodingReadme +++ /dev/null @@ -1,556 +0,0 @@ - -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 -=============== - - -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. - - - -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 -``` diff --git a/README.md b/README.md index 203a292d1..74b6170b1 100644 --- a/README.md +++ b/README.md @@ -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/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 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} -