manual/PRESENTATION_Prog.tex

   1
   2 \section{Writing Yosys extensions in C++}
   3
   4 \begin{frame}
   5 \sectionpage
   6 \end{frame}
   7
   8 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   9
  10 \subsection{Program Components and Data Formats}
  11
  12 \begin{frame}{\subsecname}
  13 \begin{center}
  14 \begin{tikzpicture}[scale=0.6, every node/.style={transform shape}]
  15         \tikzstyle{process} = [draw, fill=green!10, rectangle, minimum height=3em, minimum width=10em, node distance=15em]
  16         \tikzstyle{data} = [draw, fill=blue!10, ellipse, minimum height=3em, minimum width=7em, node distance=15em]
  17         \node[process] (vlog) {Verilog Frontend};
  18         \node[process, dashed, fill=green!5] (vhdl) [right of=vlog] {VHDL Frontend};
  19         \node[process] (ilang) [right of=vhdl] {Other Frontends};
  20         \node[data] (ast) [below of=vlog, node distance=5em, xshift=7.5em] {AST};
  21         \node[process] (astfe) [below of=ast, node distance=5em] {AST Frontend};
  22         \node[data] (rtlil) [below of=astfe, node distance=5em, xshift=7.5em] {RTLIL};
  23         \node[process] (pass) [right of=rtlil, node distance=5em, xshift=7.5em] {Passes};
  24         \node[process] (vlbe) [below of=rtlil, node distance=7em, xshift=-13em] {Verilog Backend};
  25         \node[process] (ilangbe) [below of=rtlil, node distance=7em, xshift=0em] {RTLIL Backend};
  26         \node[process, fill=green!5] (otherbe) [below of=rtlil, node distance=7em, xshift=+13em] {Other Backends};
  27
  28         \draw[-latex] (vlog) -- (ast);
  29         \draw[-latex] (vhdl) -- (ast);
  30         \draw[-latex] (ast) -- (astfe);
  31         \draw[-latex] (astfe) -- (rtlil);
  32         \draw[-latex] (ilang) -- (rtlil);
  33         \draw[latex-latex] (rtlil) -- (pass);
  34         \draw[-latex] (rtlil) -- (vlbe);
  35         \draw[-latex] (rtlil) -- (ilangbe);
  36         \draw[-latex] (rtlil) -- (otherbe);
  37 \end{tikzpicture}
  38 \end{center}
  39 \end{frame}
  40
  41 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  42
  43 \subsection{Simplified RTLIL Entity-Relationship Diagram}
  44
  45 \begin{frame}{\subsecname}
  46 Between passses and frontends/backends the design is stored in Yosys' internal
  47 RTLIL (RTL Intermediate Language) format. For writing Yosys extensions it is
  48 key to understand this format.
  49
  50 \bigskip
  51 \begin{center}
  52 \begin{tikzpicture}[scale=0.6, every node/.style={transform shape}]
  53         \tikzstyle{entity} = [draw, fill=gray!10, rectangle, minimum height=3em, minimum width=7em, node distance=5em, font={\ttfamily}]
  54         \node[entity] (design) {RTLIL::Design};
  55         \node[entity] (module) [right of=design, node distance=11em] {RTLIL::Module} edge [-latex] node[above] {\tiny 1 \hskip3em N} (design);
  56
  57         \node[entity] (process) [fill=green!10, right of=module, node distance=10em] {RTLIL::Process} (process.west) edge [-latex] (module);
  58         \node[entity] (memory) [fill=red!10, below of=process] {RTLIL::Memory} edge [-latex] (module);
  59         \node[entity] (wire) [fill=blue!10, above of=process] {RTLIL::Wire} (wire.west) edge [-latex] (module);
  60         \node[entity] (cell) [fill=blue!10, above of=wire] {RTLIL::Cell} (cell.west) edge [-latex] (module);
  61
  62         \node[entity] (case) [fill=green!10, right of=process, node distance=10em] {RTLIL::CaseRule} edge [latex-latex] (process);
  63         \node[entity] (sync) [fill=green!10, above of=case] {RTLIL::SyncRule} edge [-latex] (process);
  64         \node[entity] (switch) [fill=green!10, below of=case] {RTLIL::SwitchRule} edge [-latex] (case);
  65         \draw[latex-] (switch.east) -- ++(1em,0) |- (case.east);
  66 \end{tikzpicture}
  67 \end{center}
  68 \end{frame}
  69
  70 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  71
  72 \subsection{RTLIL without memories and processes}
  73
  74 \begin{frame}[fragile]{\subsecname}
  75 After the commands {\tt proc} and {\tt memory} (or {\tt memory -nomap}), we are
  76 left with a much simpler version of RTLIL:
  77
  78 \begin{center}
  79 \begin{tikzpicture}[scale=0.6, every node/.style={transform shape}]
  80         \tikzstyle{entity} = [draw, fill=gray!10, rectangle, minimum height=3em, minimum width=7em, node distance=5em, font={\ttfamily}]
  81         \node[entity] (design) {RTLIL::Design};
  82         \node[entity] (module) [right of=design, node distance=11em] {RTLIL::Module} edge [-latex] node[above] {\tiny 1 \hskip3em N} (design);
  83
  84         \node[entity] (wire) [fill=blue!10, right of=module, node distance=10em] {RTLIL::Wire} (wire.west) edge [-latex] (module);
  85         \node[entity] (cell) [fill=blue!10, above of=wire] {RTLIL::Cell} (cell.west) edge [-latex] (module);
  86 \end{tikzpicture}
  87 \end{center}
  88
  89 \bigskip
  90 Many commands simply choose to only work on this simpler version:
  91 \begin{lstlisting}[xleftmargin=0.5cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont]
  92 for (RTLIL::Module *module : design->selected_modules() {
  93     if (module->has_memories_warn() || module->has_processes_warn())
  94         continue;
  95     ....
  96 }
  97 \end{lstlisting}
  98
  99 For simplicity we only discuss this version of RTLIL in this presentation.
 100 \end{frame}
 101
 102 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 103
 104 \subsection{Using dump and show commands}
 105
 106 \begin{frame}{\subsecname}
 107 \begin{itemize}
 108 \item The {\tt dump} command prints the design (or parts of it) in the text representation of RTLIL.
 109
 110 \bigskip
 111 \item The {\tt show} command visualizes how the components in the design are connected.
 112 \end{itemize}
 113
 114 \bigskip
 115 When trying to understand what a command does, create a small test case and
 116 look at the output of {\tt dump} and {\tt show} before and after the command
 117 has been executed.
 118 \end{frame}
 119
 120 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 121
 122 \subsection{The RTLIL Data Structures}
 123
 124 \begin{frame}{\subsecname}
 125 The RTLIL data structures are simple structs utilizing {\tt pool<>} and
 126 {\tt dict<>} containers (drop-in replacements for {\tt
 127 std::unordered\_set<>} and {\tt std::unordered\_map<>}).
 128
 129 \bigskip
 130 \begin{itemize}
 131 \item Most operations are performed directly on the RTLIL structs without
 132 setter or getter functions.
 133
 134 \bigskip
 135 \item In debug builds a consistency checker is run over the in-memory design
 136 between commands to make sure that the RTLIL representation is intact.
 137
 138 \bigskip
 139 \item Most RTLIL structs have helper methods that perform the most common operations.
 140 \end{itemize}
 141
 142 \bigskip
 143 See {\tt yosys/kernel/rtlil.h} for details.
 144 \end{frame}
 145
 146 \subsubsection{RTLIL::IdString}
 147
 148 \begin{frame}{\subsubsecname}{}
 149 {\tt RTLIL::IdString} in many ways behave like a {\tt std::string}. It is used
 150 for names of RTLIL objects. Internally a RTLIL::IdString object is only a
 151 single integer.
 152
 153 \medskip
 154 The first character of a {\tt RTLIL::IdString} specifies if the name is {\it public\/} or {\it private\/}:
 155
 156 \medskip
 157 \begin{itemize}
 158 \item {\tt RTLIL::IdString[0] == '\textbackslash\textbackslash'}: \\
 159 This is a public name. Usually this means it is a name that was declared in a Verilog file.
 160
 161 \bigskip
 162 \item {\tt RTLIL::IdString[0] == '\$'}: \\
 163 This is a private name. It was assigned by Yosys.
 164 \end{itemize}
 165
 166 \bigskip
 167 Use the {\tt NEW\_ID} macro to create a new unique private name.
 168 \end{frame}
 169
 170 \subsubsection{RTLIL::Design and RTLIL::Module}
 171
 172 \begin{frame}[t, fragile]{\subsubsecname}
 173 The {\tt RTLIL::Design} and {\tt RTLIL::Module} structs are the top-level RTLIL
 174 data structures. Yosys always operates on one active design, but can hold many designs in memory.
 175
 176 \bigskip
 177 \begin{lstlisting}[xleftmargin=1cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=C++]
 178 struct RTLIL::Design {
 179     dict<RTLIL::IdString, RTLIL::Module*> modules_;
 180     ...
 181 };
 182
 183 struct RTLIL::Module {
 184     RTLIL::IdString name;
 185     dict<RTLIL::IdString, RTLIL::Wire*> wires_;
 186     dict<RTLIL::IdString, RTLIL::Cell*> cells_;
 187     std::vector<RTLIL::SigSig> connections_;
 188     ...
 189 };
 190 \end{lstlisting}
 191
 192 (Use the various accessor functions instead of directly working with the {\tt *\_} members.)
 193 \end{frame}
 194
 195 \subsubsection{The RTLIL::Wire Structure}
 196
 197 \begin{frame}[t, fragile]{\subsubsecname}
 198 Each wire in the design is represented by a {\tt RTLIL::Wire} struct:
 199
 200 \medskip
 201 \begin{lstlisting}[xleftmargin=1cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=C++]
 202 struct RTLIL::Wire {
 203     RTLIL::IdString name;
 204     int width, start_offset, port_id;
 205     bool port_input, port_output;
 206     ...
 207 };
 208 \end{lstlisting}
 209
 210 \medskip
 211 \hfil\begin{tabular}{p{3cm}l}
 212 {\tt width} \dotfill & The total number of bits. E.g. 10 for {\tt [9:0]}. \\
 213 {\tt start\_offset} \dotfill & The lowest bit index. E.g. 3 for {\tt [5:3]}. \\
 214 {\tt port\_id} \dotfill & Zero for non-ports. Positive index for ports. \\
 215 {\tt port\_input} \dotfill & True for {\tt input} and {\tt inout} ports. \\
 216 {\tt port\_output} \dotfill & True for {\tt output} and {\tt inout} ports. \\
 217 \end{tabular}
 218 \end{frame}
 219
 220 \subsubsection{RTLIL::State and RTLIL::Const}
 221
 222 \begin{frame}[t, fragile]{\subsubsecname}
 223 The {\tt RTLIL::State} enum represents a simple 1-bit logic level:
 224
 225 \smallskip
 226 \begin{lstlisting}[xleftmargin=1cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=C++]
 227 enum RTLIL::State {
 228     S0 = 0,
 229     S1 = 1,
 230     Sx = 2, // undefined value or conflict
 231     Sz = 3, // high-impedance / not-connected
 232     Sa = 4, // don't care (used only in cases)
 233     Sm = 5  // marker (used internally by some passes)
 234 };
 235 \end{lstlisting}
 236
 237 \bigskip
 238 The {\tt RTLIL::Const} struct represents a constant multi-bit value:
 239
 240 \smallskip
 241 \begin{lstlisting}[xleftmargin=1cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=C++]
 242 struct RTLIL::Const {
 243     std::vector<RTLIL::State> bits;
 244     ...
 245 };
 246 \end{lstlisting}
 247
 248 \bigskip
 249 Notice that Yosys is not using special {\tt VCC} or {\tt GND} driver cells to represent constants. Instead
 250 constants are part of the RTLIL representation itself.
 251 \end{frame}
 252
 253 \subsubsection{The RTLIL::SigSpec Structure}
 254
 255 \begin{frame}[t, fragile]{\subsubsecname}
 256 The {\tt RTLIL::SigSpec} struct represents a signal vector. Each bit can either be a bit from a wire
 257 or a constant value.
 258
 259 \bigskip
 260 \begin{lstlisting}[xleftmargin=1cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=C++]
 261 struct RTLIL::SigBit
 262 {
 263     RTLIL::Wire *wire;
 264     union {
 265         RTLIL::State data; // used if wire == NULL
 266         int offset;        // used if wire != NULL
 267     };
 268     ...
 269 };
 270
 271 struct RTLIL::SigSpec {
 272     std::vector<RTLIL::SigBit> bits_; // LSB at index 0
 273     ...
 274 };
 275 \end{lstlisting}
 276
 277 \bigskip
 278 The {\tt RTLIL::SigSpec} struct has a ton of additional helper methods to compare, analyze, and
 279 manipulate instances of {\tt RTLIL::SigSpec}.
 280 \end{frame}
 281
 282 \subsubsection{The RTLIL::Cell Structure}
 283
 284 \begin{frame}[t, fragile]{\subsubsecname (1/2)}
 285 The {\tt RTLIL::Cell} struct represents an instance of a module or library cell.
 286
 287 \smallskip
 288 The ports of the cell
 289 are associated with {\tt RTLIL::SigSpec} instances and the parameters are associated with {\tt RTLIL::Const}
 290 instances:
 291
 292 \bigskip
 293 \begin{lstlisting}[xleftmargin=1cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=C++]
 294 struct RTLIL::Cell {
 295     RTLIL::IdString name, type;
 296     dict<RTLIL::IdString, RTLIL::SigSpec> connections_;
 297     dict<RTLIL::IdString, RTLIL::Const> parameters;
 298     ...
 299 };
 300 \end{lstlisting}
 301
 302 \bigskip
 303 The {\tt type} may refer to another module in the same design, a cell name from a cell library, or a
 304 cell name from the internal cell library:
 305
 306 \begin{lstlisting}[xleftmargin=1cm, basicstyle=\ttfamily\fontsize{6pt}{7pt}\selectfont]
 307 $not $pos $neg $and $or $xor $xnor $reduce_and $reduce_or $reduce_xor $reduce_xnor
 308 $reduce_bool $shl $shr $sshl $sshr $lt $le $eq $ne $eqx $nex $ge $gt $add $sub $mul $div $mod
 309 $divfloor $modfloor $pow $logic_not $logic_and $logic_or $mux $pmux $slice $concat $lut $assert $sr $dff
 310 $dffsr $adff $dlatch $dlatchsr $memrd $memwr $mem $fsm $_NOT_ $_AND_ $_OR_ $_XOR_ $_MUX_ $_SR_NN_
 311 $_SR_NP_ $_SR_PN_ $_SR_PP_ $_DFF_N_ $_DFF_P_ $_DFF_NN0_ $_DFF_NN1_ $_DFF_NP0_ $_DFF_NP1_ $_DFF_PN0_
 312 $_DFF_PN1_ $_DFF_PP0_ $_DFF_PP1_ $_DFFSR_NNN_ $_DFFSR_NNP_ $_DFFSR_NPN_ $_DFFSR_NPP_ $_DFFSR_PNN_
 313 $_DFFSR_PNP_ $_DFFSR_PPN_ $_DFFSR_PPP_ $_DLATCH_N_ $_DLATCH_P_ $_DLATCHSR_NNN_ $_DLATCHSR_NNP_
 314 $_DLATCHSR_NPN_ $_DLATCHSR_NPP_ $_DLATCHSR_PNN_ $_DLATCHSR_PNP_ $_DLATCHSR_PPN_ $_DLATCHSR_PPP_
 315 \end{lstlisting}
 316 \end{frame}
 317
 318 \begin{frame}[t, fragile]{\subsubsecname (2/2)}
 319 Simulation models (i.e. {\it documentation\/} :-) for the internal cell library:
 320
 321 \smallskip
 322 \hskip2em {\tt yosys/techlibs/common/simlib.v} and \\
 323 \hskip2em {\tt yosys/techlibs/common/simcells.v}
 324
 325 \bigskip
 326 The lower-case cell types (such as {\tt \$and}) are parameterized cells of variable
 327 width. This so-called {\it RTL Cells\/} are the cells described in {\tt simlib.v}.
 328
 329 \bigskip
 330 The upper-case cell types (such as {\tt \$\_AND\_}) are single-bit cells that are not
 331 parameterized. This so-called {\it Internal Logic Gates} are the cells described
 332 in {\tt simcells.v}.
 333
 334 \bigskip
 335 The consistency checker also checks the interfaces to the internal cell library.
 336 If you want to use private cell types for your own purposes, use the {\tt \$\_\_}-prefix
 337 to avoid name collisions.
 338 \end{frame}
 339
 340 \subsubsection{Connecting wires or constant drivers}
 341
 342 \begin{frame}[t, fragile]{\subsubsecname}
 343 Additional connections between wires or between wires and constants are modelled using
 344 {\tt RTLIL::Module::connections}:
 345
 346 \bigskip
 347 \begin{lstlisting}[xleftmargin=1cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=C++]
 348 typedef std::pair<RTLIL::SigSpec, RTLIL::SigSpec> RTLIL::SigSig;
 349
 350 struct RTLIL::Module {
 351     ...
 352     std::vector<RTLIL::SigSig> connections_;
 353     ...
 354 };
 355 \end{lstlisting}
 356
 357 \bigskip
 358 {\tt RTLIL::SigSig::first} is the driven signal and {\tt RTLIL::SigSig::second} is the driving signal.
 359 Example usage (setting wire {\tt foo} to value {\tt 42}):
 360 \begin{lstlisting}[xleftmargin=1cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=C++]
 361 module->connect(module->wire("\\foo"),
 362                 RTLIL::SigSpec(42, module->wire("\\foo")->width));
 363 \end{lstlisting}
 364 \end{frame}
 365
 366 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 367
 368 \subsection{Creating modules from scratch}
 369
 370 \begin{frame}[t, fragile]{\subsecname}
 371 Let's create the following module using the RTLIL API:
 372
 373 \smallskip
 374 \begin{lstlisting}[xleftmargin=1cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=Verilog]
 375 module absval(input signed [3:0] a, output [3:0] y);
 376     assign y = a[3] ? -a : a;
 377 endmodule
 378 \end{lstlisting}
 379
 380 \smallskip
 381 \begin{lstlisting}[xleftmargin=1cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=C++]
 382 RTLIL::Module *module = new RTLIL::Module;
 383 module->name = "\\absval";
 384
 385 RTLIL::Wire *a = module->addWire("\\a", 4);
 386 a->port_input = true;
 387 a->port_id = 1;
 388
 389 RTLIL::Wire *y = module->addWire("\\y", 4);
 390 y->port_output = true;
 391 y->port_id = 2;
 392
 393 RTLIL::Wire *a_inv = module->addWire(NEW_ID, 4);
 394 module->addNeg(NEW_ID, a, a_inv, true);
 395 module->addMux(NEW_ID, a, a_inv, RTLIL::SigSpec(a, 1, 3), y);
 396
 397 module->fixup_ports();
 398 \end{lstlisting}
 399 \end{frame}
 400
 401 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 402
 403 \subsection{Modifying modules}
 404
 405 \begin{frame}{\subsecname}
 406 Most commands modify existing modules, not create new ones.
 407
 408 When modifying existing modules, stick to the following DOs and DON'Ts:
 409
 410 \begin{itemize}
 411 \item Do not remove wires. Simply disconnect them and let a successive {\tt clean} command worry about removing it.
 412
 413 \item Use {\tt module->fixup\_ports()} after changing the {\tt port\_*} properties of wires.
 414
 415 \item You can safely remove cells or change the {\tt connections} property of a cell, but be careful when
 416 changing the size of the {\tt SigSpec} connected to a cell port.
 417
 418 \item Use the {\tt SigMap} helper class (see next slide) when you need a unique handle for each signal bit.
 419 \end{itemize}
 420 \end{frame}
 421
 422 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 423
 424 \subsection{Using the SigMap helper class}
 425
 426 \begin{frame}[t, fragile]{\subsecname}
 427 Consider the following module:
 428
 429 \smallskip
 430 \begin{lstlisting}[xleftmargin=1cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=Verilog]
 431 module test(input a, output x, y);
 432     assign x = a, y = a;
 433 endmodule
 434 \end{lstlisting}
 435
 436 In this case {\tt a}, {\tt x}, and {\tt y} are all different names for the same signal. However:
 437
 438 \smallskip
 439 \begin{lstlisting}[xleftmargin=1cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=C++]
 440 RTLIL::SigSpec a(module->wire("\\a")), x(module->wire("\\x")),
 441                                        y(module->wire("\\y"));
 442 log("%d %d %d\n", a == x, x == y, y == a); // will print "0 0 0"
 443 \end{lstlisting}
 444
 445 The {\tt SigMap} helper class can be used to map all such aliasing signals to a
 446 unique signal from the group (usually the wire that is directly driven by a cell or port).
 447
 448 \smallskip
 449 \begin{lstlisting}[xleftmargin=1cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=C++]
 450 SigMap sigmap(module);
 451 log("%d %d %d\n", sigmap(a) == sigmap(x), sigmap(x) == sigmap(y),
 452                   sigmap(y) == sigmap(a)); // will print "1 1 1"
 453 \end{lstlisting}
 454 \end{frame}
 455
 456 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 457
 458 \subsection{Printing log messages}
 459
 460 \begin{frame}[t, fragile]{\subsecname}
 461 The {\tt log()} function is a {\tt printf()}-like function that can be used to create log messages.
 462
 463 \medskip
 464 Use {\tt log\_signal()} to create a C-string for a SigSpec object\footnote[frame]{The pointer returned
 465 by {\tt log\_signal()} is automatically freed by the log framework at a later time.}:
 466 \begin{lstlisting}[xleftmargin=1cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=C++]
 467 log("Mapped signal x: %s\n", log_signal(sigmap(x)));
 468 \end{lstlisting}
 469
 470 \medskip
 471 Use {\tt log\_id()} to create a C-string for an {\tt RTLIL::IdString}:
 472 \begin{lstlisting}[xleftmargin=1cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=C++]
 473 log("Name of this module: %s\n", log_id(module->name));
 474 \end{lstlisting}
 475
 476 \medskip
 477 Use {\tt log\_header()} and {\tt log\_push()}/{\tt log\_pop()} to structure log messages:
 478 \begin{lstlisting}[xleftmargin=1cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=C++]
 479 log_header(design, "Doing important stuff!\n");
 480 log_push();
 481 for (int i = 0; i < 10; i++)
 482     log("Log message #%d.\n", i);
 483 log_pop();
 484 \end{lstlisting}
 485 \end{frame}
 486
 487 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 488
 489 \subsection{Error handling}
 490
 491 \begin{frame}[t, fragile]{\subsecname}
 492 Use {\tt log\_error()} to report a non-recoverable error:
 493
 494 \medskip
 495 \begin{lstlisting}[xleftmargin=1cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=C++]
 496 if (design->modules.count(module->name) != 0)
 497     log_error("A module with the name %s already exists!\n",
 498             RTLIL::id2cstr(module->name));
 499 \end{lstlisting}
 500
 501 \bigskip
 502 Use {\tt log\_cmd\_error()} to report a recoverable error:
 503 \begin{lstlisting}[xleftmargin=1cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=C++]
 504 if (design->selection_stack.back().empty())
 505     log_cmd_error("This command can't operator on an empty selection!\n");
 506 \end{lstlisting}
 507
 508 \bigskip
 509 Use {\tt log\_assert()} and {\tt log\_abort()} instead of {\tt assert()} and {\tt abort()}.
 510 \end{frame}
 511
 512 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 513
 514 \subsection{Creating a command}
 515
 516 \begin{frame}[t, fragile]{\subsecname}
 517 Simply create a global instance of a class derived from {\tt Pass} to create
 518 a new yosys command:
 519
 520 \bigskip
 521 \begin{lstlisting}[xleftmargin=1cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont, language=C++]
 522 #include "kernel/yosys.h"
 523 USING_YOSYS_NAMESPACE
 524
 525 struct MyPass : public Pass {
 526     MyPass() : Pass("my_cmd", "just a simple test") { }
 527     virtual void execute(std::vector<std::string> args, RTLIL::Design *design)
 528     {
 529         log("Arguments to my_cmd:\n");
 530         for (auto &arg : args)
 531             log("  %s\n", arg.c_str());
 532
 533         log("Modules in current design:\n");
 534         for (auto mod : design->modules())
 535             log("  %s (%d wires, %d cells)\n", log_id(mod),
 536                     GetSize(mod->wires()), GetSize(mod->cells()));
 537     }
 538 } MyPass;
 539 \end{lstlisting}
 540 \end{frame}
 541
 542 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 543
 544 \subsection{Creating a plugin}
 545
 546 \begin{frame}[fragile]{\subsecname}
 547 Yosys can be extended by adding additional C++ code to the Yosys code base, or
 548 by loading plugins into Yosys.
 549
 550 \bigskip
 551 Use the following command to compile a Yosys plugin:
 552 \begin{lstlisting}[xleftmargin=1cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont]
 553 yosys-config --exec --cxx --cxxflags --ldflags \
 554              -o my_cmd.so -shared my_cmd.cc --ldlibs
 555 \end{lstlisting}
 556
 557 \bigskip
 558 Or shorter:
 559 \begin{lstlisting}[xleftmargin=1cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont]
 560 yosys-config --build my_cmd.so my_cmd.cc
 561 \end{lstlisting}
 562
 563 \bigskip
 564 Load the plugin using the yosys {\tt -m} option:
 565 \begin{lstlisting}[xleftmargin=1cm, basicstyle=\ttfamily\fontsize{8pt}{10pt}\selectfont]
 566 yosys -m ./my_cmd.so -p 'my_cmd foo bar'
 567 \end{lstlisting}
 568 \end{frame}
 569
 570 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 571
 572 \subsection{Summary}
 573
 574 \begin{frame}{\subsecname}
 575 \begin{itemize}
 576 \item Writing Yosys extensions is very straight-forward.
 577 \item \dots and even simpler if you don't need RTLIL::Memory or RTLIL::Process objects.
 578
 579 \bigskip
 580 \item Writing synthesis software? Consider learning the Yosys API and make your work
 581 part of the Yosys framework.
 582 \end{itemize}
 583
 584 \bigskip
 585 \bigskip
 586 \begin{center}
 587 Questions?
 588 \end{center}
 589
 590 \bigskip
 591 \bigskip
 592 \begin{center}
 593 \url{http://www.clifford.at/yosys/}
 594 \end{center}
 595 \end{frame}
 596