struct HelloWorldPass : public Pass {
HelloWorldPass() : Pass("hello_world") { }
- virtual void execute(vector<string>, Design*) {
+ void execute(vector<string>, Design*) override {
log("Hello World!\n");
}
} HelloWorldPass;
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
- 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<K, T> and pool<T> will have the same order of iteration across
all compilers, standard libraries and architectures.
It is not possible to remove elements from an idict.
+Finally mfp<K> 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<T> and std::string whenever applicable. When
table.)
RTLIL::SigBit
- A single signal bit. I.e. either a constant (0, 1, x, z) or
- a single bit from a wire.
+ 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.
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 consitently
+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);
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, Cell*> 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
------------
of how to use the Yosys API:
manual/CHAPTER_Prog/stubnets.cc
- passes/opt/wreduce.cc
- passes/techmap/maccmap.cc
+ manual/PRESENTATION_Prog/my_cmd.cc
Notes on the existing codebase
on its own line for larger blocks, especially blocks that contains
blank lines.
-- Otherwise stick to the Linux Kernel Coding Stlye:
+- Otherwise stick to the Linux Kernel Coding Style:
https://www.kernel.org/doc/Documentation/CodingStyle
-C++ Langugage
+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
[ ] Add to source control
[X] Console applications
- [X] Empty Projcect
+ [X] Empty Project
[ ] SDL checks
2. Open YosysVS Project Properties
- 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
+ - Maybe add support to the Verilog backend for dumping such cells as expression
vi CHANGELOG
-Run all tests with "make config-{clang,gcc,gcc-4.6}":
+Update and check documentation:
cd ~yosys
- make clean
- make test vloghtb
- make install
-
- cd ~yosys-bigsim
- make clean
- make full
+ 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 ~vloghammer
- make purge gen_issues gen_samples
- make SYN_LIST="yosys" SIM_LIST="icarus yosim verilator" REPORT_FULL=1 world
- chromium-browser report.html
+ 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
- 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
-
-
-Also with default config setting:
-
- cd ~yosys/techlibs/cmos
+ cd ~yosys/examples/cmos
bash testbench.sh
- cd ~yosys/techlibs/xilinx/example_sim_counter
- bash run_sim.sh
-
- cd ~yosys/techlibs/xilinx/example_mojo_counter
- bash example.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
-Finally if a current verific library is available:
+And if a version of the verific library is currently available:
cd ~yosys
cat frontends/verific/build_amd64.txt
../../yosys test_navre.ys
-Release candiate:
+Finally run all tests with "make config-{clang,gcc,gcc-4.8}":
- - create branch yosys-x.y.z-rc and push to github
- - contact the usual suspects per mail and ask them to test
- - post on the reddit and ask people to test
- - commit KISS fixes to the -rc branch if necessary
+ 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:
- push tag to github
- post changelog on github
- post short release note on reddit
- - delete -rc branch from github
Updating the website:
make push
-In master branch:
- git merge {release-tag}
- - set version to x.y.z+ in Makefile
- - add section "Yosys x.y.z .. x.y.z+" to CHANGELOG
- git commit --amend -am "Yosys x.y.z+"
+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
+```