yosys/CodingReadme

Getting Started
===============


Reading List
------------

To write Yosys C++ code you need to know at least the following classes in kernel/rtlil.h:

	RTLIL::Wire
	RTLIL::Cell
	RTLIL::Module
	RTLIL::SigSpec

The following yosys commands are a good starting point if you are looking for examples
of how to use the Yosys API:

	passes/opt/wreduce.cc
	passes/techmap/maccmap.cc


Notes on the existing codebase
------------------------------

For historical reasons not all parts of Yosys adhere to the current coding
styles.  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 Stlye:
    https://www.kernel.org/doc/Documentation/CodingStyle


C++ Langugage
-------------

Yosys is written in C++11. At the moment only constructs supported by
gcc 4.6 is 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 by kernel/yosys.h)

Use range-based for loops whenever applicable.



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 Projcect
	[ ] 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


Run all tests with "make config-{clang-debug,gcc-debug,gcc-4.6,release}":

	cd ~yosys
	make clean
	make test vloghtb
	make install

	cd ~yosys-bigsim
	make clean
	make full

	cd ~vloghammer
	make purge
	make gen_issues gen_samples
	make SYN_LIST="yosys" SIM_LIST="icarus yosim verilator" FULL=1 world
	chromium-browser report.html


Then with default config setting:

	cd ~yosys
	./yosys -p 'proc; show' tests/simple/fiedler-cooley.v
	./yosys -p 'proc; opt; 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
	bash testbench.sh

	cd ~yosys/techlibs/xilinx/example_sim_counter
	bash run_sim.sh

	cd ~yosys/techlibs/xilinx/example_mojo_counter
	bash example.sh


Finally if a current verific library is available:

	cd ~yosys
	cat frontends/verific/build_amd64.txt
	- follow instructions

	cd frontends/verific
	../../yosys test_navre.ys


Release candiate:

	- 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


Release:

	- set YOSYS_VER to x.y.z in 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
	- delete -rc branch from github


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


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+"