X-Git-Url: https://git.libre-soc.org/?a=blobdiff_plain;f=CodingReadme;h=7d4ded93d2ffb12e88b81d0a254f6b804c6e1127;hb=63246a5c0eb5780675384d00443e6e46b5e59603;hp=5d5d9b32ce9622bde5a9eaf6653dbb5c6d691550;hpb=4d0a6dac7b865a38b587cda3e1c13b16ee284deb;p=yosys.git diff --git a/CodingReadme b/CodingReadme index 5d5d9b32c..7d4ded93d 100644 --- a/CodingReadme +++ b/CodingReadme @@ -21,7 +21,7 @@ Here is a the C++ code for a "hello_world" Yosys command (hello.cc): struct HelloWorldPass : public Pass { HelloWorldPass() : Pass("hello_world") { } - virtual void execute(vector, Design*) { + void execute(vector, Design*) override { log("Hello World!\n"); } } HelloWorldPass; @@ -94,7 +94,7 @@ creates a bijective map from K to the integers. For example: 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). +union-find) over the type K ("mfp" = merge-find-promote). 2. Standard STL data types @@ -202,6 +202,52 @@ of how to use the Yosys API: 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 ------------------------------ @@ -239,7 +285,7 @@ C++ Language ------------- Yosys is written in C++11. At the moment only constructs supported by -gcc 4.6 are allowed in Yosys code. This will change in future releases. +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 @@ -368,11 +414,12 @@ And if a version of the verific library is currently available: ../../yosys test_navre.ys -Finally run all tests with "make config-{clang,gcc,gcc-4.6}": +Finally run all tests with "make config-{clang,gcc,gcc-4.8}": cd ~yosys make clean make test + make ystests make vloghtb make install @@ -389,6 +436,7 @@ Finally run all tests with "make config-{clang,gcc,gcc-4.6}": 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" @@ -411,3 +459,98 @@ Updating the website: 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 +```