\chapter{RTLIL Text Representation} \label{chapter:textrtlil} % Stolen from stackexchange: calculate indent based on given keyword, % with some nice hrules added in. \newlength{\myl} \newenvironment{indentgrammar}[1] {\vspace{0.5cm}\hrule \setlength{\myl}{\widthof{#1}+2em} \grammarindent\the\myl \begin{grammar}} {\end{grammar} \hrule} This appendix documents the text representation of RTLIL in extended Backus-Naur form (EBNF). The grammar is not meant to represent semantic limitations. That is, the grammar is ``permissive'', and later stages of processing perform more rigorous checks. The grammar is also not meant to represent the exact grammar used in the RTLIL frontend, since that grammar is specific to processing by lex and yacc, is even more permissive, and is somewhat less understandable than simple EBNF notation. Finally, note that all statements (rules ending in \texttt{-stmt}) terminate in an end-of-line. Because of this, a statement cannot be broken into multiple lines. \section{Lexical elements} \subsection{Characters} An RTLIL file is a stream of bytes. Strictly speaking, a ``character'' in an RTLIL file is a single byte. The lexer treats multi-byte encoded characters as consecutive single-byte characters. While other encodings \textit{may} work, UTF-8 is known to be safe to use. Byte order marks at the beginning of the file will cause an error. ASCII spaces (32) and tabs (9) separate lexer tokens. A \texttt{nonws} character, used in identifiers, is any character whose encoding consists solely of bytes above ASCII space (32). An \texttt{eol} is one or more consecutive ASCII newlines (10) and carriage returns (13). \subsection{Identifiers} There are two types of identifiers in RTLIL: \begin{itemize} \item Publically visible identifiers \item Auto-generated identifiers \end{itemize} \begin{indentgrammar}{} ::= |

::= "\textbackslash" $+$ ::= "\textdollar" $+$ \end{indentgrammar} \subsection{Values} A \textit{value} consists of a width in bits and a bit representation, most significant bit first. Bits may be any of: \begin{itemize} \item \texttt{0}: A logic zero value \item \texttt{1}: A logic one value \item \texttt{x}: An unknown logic value (or don't care in case patterns) \item \texttt{z}: A high-impedance value (or don't care in case patterns) \item \texttt{m}: A marked bit (internal use only) \item \texttt{-}: A don't care value \end{itemize} An \textit{integer} is simply a signed integer value in decimal format. \textbf{Warning:} Integer constants are limited to 32 bits. That is, they may only be in the range $[-2147483648, 2147483648)$. Integers outside this range will result in an error. \begin{indentgrammar}{} ::= $+$ \texttt{\textbf{'}} $*$ ::= "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ::= "0" | "1" | "x" | "z" | "m" | "-" ::= "-"$?$ $+$ \end{indentgrammar} \subsection{Strings} A string is a series of characters delimited by double-quote characters. Within a string, any character except ASCII NUL (0) may be used. In addition, certain escapes can be used: \begin{itemize} \item \texttt{\textbackslash n}: A newline \item \texttt{\textbackslash t}: A tab \item \texttt{\textbackslash \textit{ooo}}: A character specified as a one, two, or three digit octal value \end{itemize} All other characters may be escaped by a backslash, and become the following character. Thus: \begin{itemize} \item \texttt{\textbackslash \textbackslash}: A backslash \item \texttt{\textbackslash ''}: A double-quote \item \texttt{\textbackslash r}: An 'r' character \end{itemize} \subsection{Comments} A comment starts with a \texttt{\textbf{\#}} character and proceeds to the end of the line. All comments are ignored. \section{File} A file consists of an optional autoindex statement followed by zero or more modules. \begin{indentgrammar}{} ::= $?$ * \end{indentgrammar} \subsection{Autoindex statements} The autoindex statement sets the global autoindex value used by Yosys when it needs to generate a unique name, e.g. \texttt{\textdollar{}flatten\textdollar{}N}. The N part is filled with the value of the global autoindex value, which is subsequently incremented. This global has to be dumped into RTLIL, otherwise e.g. dumping and running a pass would have different properties than just running a pass on a warm design. \begin{indentgrammar}{} ::= "autoidx" \end{indentgrammar} \subsection{Modules} Declares a module, with zero or more attributes, consisting of zero or more wires, memories, cells, processes, and connections. \begin{indentgrammar}{} ::= $*$

::= "module"

::= ( \alt \alt \alt \alt \alt )$*$ ::= "parameter" $?$ ::= | |

::= "end" \end{indentgrammar} \subsection{Attribute statements} Declares an attribute with the given identifier and value. \begin{indentgrammar}{} ::= "attribute" \end{indentgrammar} \subsection{Signal specifications} A signal is anything that can be applied to a cell port, i.e. a constant value, all bits or a selection of bits from a wire, or concatenations of those. \textbf{Warning:} When an integer constant is a sigspec, it is always 32 bits wide, 2's complement. For example, a constant of $-1$ is the same as \texttt{32'11111111111111111111111111111111}, while a constant of $1$ is the same as \texttt{32'1}. See Sec.~\ref{sec:rtlil_sigspec} for an overview of signal specifications. \begin{indentgrammar}{} ::= \alt \alt "[" (":" )$?$ "]" \alt "\{" $*$ "\}" \end{indentgrammar} \subsection{Connections} Declares a connection between the given signals. \begin{indentgrammar}{} ::= "connect" \end{indentgrammar} \subsection{Wires} Declares a wire, with zero or more attributes, with the given identifier and options in the enclosing module. See Sec.~\ref{sec:rtlil_cell_wire} for an overview of wires. \begin{indentgrammar}{} ::= $*$

::= "wire" $*$

::=

::= "width" \alt "offset" \alt "input" \alt "output" \alt "inout" \alt "upto" \alt "signed" \end{indentgrammar} \subsection{Memories} Declares a memory, with zero or more attributes, with the given identifier and options in the enclosing module. See Sec.~\ref{sec:rtlil_memory} for an overview of memory cells, and Sec.~\ref{sec:memcells} for details about memory cell types. \begin{indentgrammar}{} ::= $*$

::= "memory" $*$

::= "width" \alt "size" \alt "offset" \end{indentgrammar} \subsection{Cells} Declares a cell, with zero or more attributes, with the given identifier and type in the enclosing module. Cells perform functions on input signals. See Chap.~\ref{chapter:celllib} for a detailed list of cell types. \begin{indentgrammar}{} ::= $*$

$*$

::= "cell"

::=

::= "parameter" ("signed" | "real")$?$ \alt "connect"

::= "end" \end{indentgrammar} \subsection{Processes} Declares a process, with zero or more attributes, with the given identifier in the enclosing module. The body of a process consists of zero or more assignments, exactly one switch, and zero or more syncs. See Sec.~\ref{sec:rtlil_process} for an overview of processes. \begin{indentgrammar}{} ::= $*$

::= "process"

::= $*$ $?$ $*$ $*$ ::= "assign"

::=

::= "end" \end{indentgrammar} \subsection{Switches} Switches test a signal for equality against a list of cases. Each case specifies a comma-separated list of signals to check against. If there are no signals in the list, then the case is the default case. The body of a case consists of zero or more switches and assignments. Both switches and cases may have zero or more attributes. \begin{indentgrammar}{} ::= $*$

:= $*$ "switch" ::= $*$

::= "case" $?$ ::= ("," )$*$ ::= ( | )$*$ ::= "end" \end{indentgrammar} \subsection{Syncs} Syncs update signals with other signals when an event happens. Such an event may be: \begin{itemize} \item An edge or level on a signal \item Global clock ticks \item Initialization \item Always \end{itemize} \begin{indentgrammar}{} ::=

$*$ ::= "sync" \alt "sync" "global" \alt "sync" "init" \alt "sync" "always"

::= "low" | "high" | "posedge" | "negedge" | "edge" ::= "update"

\end{indentgrammar} '#n193'>193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525

# Defining a Mock Class #

## Mocking a Normal Class ##

Given
```
class Foo {
  ...
  virtual ~Foo();
  virtual int GetSize() const = 0;
  virtual string Describe(const char* name) = 0;
  virtual string Describe(int type) = 0;
  virtual bool Process(Bar elem, int count) = 0;
};
```
(note that `~Foo()` **must** be virtual) we can define its mock as
```
#include <gmock/gmock.h>

class MockFoo : public Foo {
  MOCK_CONST_METHOD0(GetSize, int());
  MOCK_METHOD1(Describe, string(const char* name));
  MOCK_METHOD1(Describe, string(int type));
  MOCK_METHOD2(Process, bool(Bar elem, int count));
};
```

To create a "nice" mock object which ignores all uninteresting calls,
or a "strict" mock object, which treats them as failures:
```
NiceMock<MockFoo> nice_foo;     // The type is a subclass of MockFoo.
StrictMock<MockFoo> strict_foo; // The type is a subclass of MockFoo.
```

## Mocking a Class Template ##

To mock
```
template <typename Elem>
class StackInterface {
 public:
  ...
  virtual ~StackInterface();
  virtual int GetSize() const = 0;
  virtual void Push(const Elem& x) = 0;
};
```
(note that `~StackInterface()` **must** be virtual) just append `_T` to the `MOCK_*` macros:
```
template <typename Elem>
class MockStack : public StackInterface<Elem> {
 public:
  ...
  MOCK_CONST_METHOD0_T(GetSize, int());
  MOCK_METHOD1_T(Push, void(const Elem& x));
};
```

## Specifying Calling Conventions for Mock Functions ##

If your mock function doesn't use the default calling convention, you
can specify it by appending `_WITH_CALLTYPE` to any of the macros
described in the previous two sections and supplying the calling
convention as the first argument to the macro. For example,
```
  MOCK_METHOD_1_WITH_CALLTYPE(STDMETHODCALLTYPE, Foo, bool(int n));
  MOCK_CONST_METHOD2_WITH_CALLTYPE(STDMETHODCALLTYPE, Bar, int(double x, double y));