From 539dd805f44ece3e39f4c68e4ea1bdc9b662e83f Mon Sep 17 00:00:00 2001 From: Clifford Wolf Date: Wed, 31 Dec 2014 14:26:54 +0100 Subject: [PATCH] Improvements in CodingReadme --- CodingReadme | 33 ++++++++++++++++++++++++--------- manual/CHAPTER_Prog.tex | 21 +++++++++++++-------- 2 files changed, 37 insertions(+), 17 deletions(-) diff --git a/CodingReadme b/CodingReadme index bdadf821d..2349b2ee2 100644 --- a/CodingReadme +++ b/CodingReadme @@ -1,5 +1,10 @@ +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 =============== @@ -42,13 +47,21 @@ 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 -essentially a replacement for std::unordered_set. The main differences are: +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 operations (just like you are used from std::vector). + 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. - dict and pool will have the same order of iteration across all compilers and architectures. @@ -97,12 +110,12 @@ 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). +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 -consitently only uses one wire from a group of connected wires. For example: +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 +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); @@ -162,7 +175,7 @@ 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. +gcc 4.6 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 @@ -171,6 +184,8 @@ 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 =========================================== diff --git a/manual/CHAPTER_Prog.tex b/manual/CHAPTER_Prog.tex index 3918594a2..3cbc95a19 100644 --- a/manual/CHAPTER_Prog.tex +++ b/manual/CHAPTER_Prog.tex @@ -2,16 +2,21 @@ \chapter{Programming Yosys Extensions} \label{chapter:prog} -\begin{fixme} -This chapter will contain a guided tour to the Yosys APIs and conclude -with an example module. -\end{fixme} +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. -\section{Programming with RTLIL} -\section{Internal Utility Libraries} -\section{Loadable Modules} +\section{The ``CodingReadme'' File} + +The following is an excerpt of the {\tt CodingReadme} file from the Yosys source tree. + +\lstinputlisting[title=CodingReadme,rangeprefix=--,rangesuffix=--,includerangemarker=false,linerange=snip-snap,numbers=left,frame=single]{../CodingReadme} + +\section{The ``stubsnets'' Example Module} + +The following is the complete code of the ``stubsnets'' example module. It is included in the Yosys source distribution as {\tt manual/CHAPTER\_Prog/stubnets.cc}. -\section{Example Module} \lstinputlisting[title=stubnets.cc,numbers=left,frame=single,language=C++]{CHAPTER_Prog/stubnets.cc} -- 2.30.2