manual/CHAPTER_TextRtlil.tex

   1 \chapter{RTLIL Text Representation}
   2 \label{chapter:textrtlil}
   3
   4 % Stolen from stackexchange: calculate indent based on given keyword,
   5 % with some nice hrules added in.
   6 \newlength{\myl}
   7
   8 \newenvironment{indentgrammar}[1]
   9     {\vspace{0.5cm}\hrule
  10     \setlength{\myl}{\widthof{#1}+2em}
  11     \grammarindent\the\myl
  12     \begin{grammar}}
  13     {\end{grammar}
  14     \hrule}
  15
  16 This appendix documents the text representation of RTLIL in extended Backus-Naur form (EBNF).
  17
  18 The grammar is not meant to represent semantic limitations. That is, the grammar is ``permissive'', and later stages of processing perform more rigorous checks.
  19
  20 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.
  21
  22 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.
  23
  24 \section{Lexical elements}
  25
  26 \subsection{Characters}
  27
  28 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.
  29
  30 ASCII spaces (32) and tabs (9) separate lexer tokens.
  31
  32 A \texttt{nonws} character, used in identifiers, is any character whose encoding consists solely of bytes above ASCII space (32).
  33
  34 An \texttt{eol} is one or more consecutive ASCII newlines (10) and carriage returns (13).
  35
  36 \subsection{Identifiers}
  37
  38 There are two types of identifiers in RTLIL:
  39
  40 \begin{itemize}
  41     \item Publically visible identifiers
  42     \item Auto-generated identifiers
  43 \end{itemize}
  44
  45 \begin{indentgrammar}{<autogen-id>}
  46 <id> ::= <public-id> | <autogen-id>
  47
  48 <public-id> ::= "\textbackslash" <nonws>$+$
  49
  50 <autogen-id> ::= "\textdollar" <nonws>$+$
  51 \end{indentgrammar}
  52
  53 \subsection{Values}
  54
  55 A \textit{value} consists of a width in bits and a bit representation, most significant bit first. Bits may be any of:
  56 \begin{itemize}
  57     \item \texttt{0}: A logic zero value
  58     \item \texttt{1}: A logic one value
  59     \item \texttt{x}: An unknown logic value (or don't care in case patterns)
  60     \item \texttt{z}: A high-impedance value (or don't care in case patterns)
  61     \item \texttt{m}: A marked bit (internal use only)
  62     \item \texttt{-}: A don't care value
  63 \end{itemize}
  64
  65 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.
  66
  67 \begin{indentgrammar}{<binary-digit>}
  68 <value> ::= <decimal-digit>$+$ \texttt{\textbf{'}} <binary-digit>$*$
  69
  70 <decimal-digit> ::= "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
  71
  72 <binary-digit> ::= "0" | "1" | "x" | "z" | "m" | "-"
  73
  74 <integer> ::= "-"$?$ <decimal-digit>$+$
  75 \end{indentgrammar}
  76
  77 \subsection{Strings}
  78
  79 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:
  80
  81 \begin{itemize}
  82     \item \texttt{\textbackslash n}: A newline
  83     \item \texttt{\textbackslash t}: A tab
  84     \item \texttt{\textbackslash \textit{ooo}}: A character specified as a one, two, or three digit octal value
  85 \end{itemize}
  86
  87 All other characters may be escaped by a backslash, and become the following character. Thus:
  88
  89 \begin{itemize}
  90     \item \texttt{\textbackslash \textbackslash}: A backslash
  91     \item \texttt{\textbackslash ''}: A double-quote
  92     \item \texttt{\textbackslash r}: An 'r' character
  93 \end{itemize}
  94
  95 \subsection{Comments}
  96
  97 A comment starts with a \texttt{\textbf{\#}} character and proceeds to the end of the line. All comments are ignored.
  98
  99 \section{File}
 100
 101 A file consists of an optional autoindex statement followed by zero or more modules.
 102
 103 \begin{indentgrammar}{<design>}
 104 <file> ::= <autoidx-stmt>$?$ <module>*
 105 \end{indentgrammar}
 106
 107 \subsection{Autoindex statements}
 108
 109 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.
 110
 111 \begin{indentgrammar}{<autoidx-stmt>}
 112 <autoidx-stmt> ::= "autoidx" <integer> <eol>
 113 \end{indentgrammar}
 114
 115 \subsection{Modules}
 116
 117 Declares a module, with zero or more attributes, consisting of zero or more wires, memories, cells, processes, and connections.
 118
 119 \begin{indentgrammar}{<module-body-stmt>}
 120 <module> ::= <attr-stmt>$*$ <module-stmt> <module-body> <module-end-stmt>
 121
 122 <module-stmt> ::= "module" <id> <eol>
 123
 124 <module-body> ::=
 125 (<param-stmt>
 126   \alt <wire>
 127   \alt <memory>
 128   \alt <cell>
 129   \alt <process>
 130   \alt <conn-stmt>)$*$
 131
 132 <param-stmt> ::= "parameter" <id> <constant>$?$ <eol>
 133
 134 <constant> ::= <value> | <integer> | <string>
 135
 136 <module-end-stmt> ::= "end" <eol>
 137 \end{indentgrammar}
 138
 139 \subsection{Attribute statements}
 140
 141 Declares an attribute with the given identifier and value.
 142
 143 \begin{indentgrammar}{<attr-stmt>}
 144 <attr-stmt> ::= "attribute" <id> <constant> <eol>
 145 \end{indentgrammar}
 146
 147 \subsection{Signal specifications}
 148
 149 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.
 150
 151 \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}.
 152
 153 See Sec.~\ref{sec:rtlil_sigspec} for an overview of signal specifications.
 154
 155 \begin{indentgrammar}{<sigspec>}
 156 <sigspec> ::=
 157 <constant>
 158     \alt <wire-id>
 159     \alt <sigspec> "[" <integer> (":" <integer>)$?$ "]"
 160     \alt "\{" <sigspec>$*$ "\}"
 161 \end{indentgrammar}
 162
 163 \subsection{Connections}
 164
 165 Declares a connection between the given signals.
 166
 167 \begin{indentgrammar}{<conn-stmt>}
 168 <conn-stmt> ::= "connect" <sigspec> <sigspec> <eol>
 169 \end{indentgrammar}
 170
 171 \subsection{Wires}
 172
 173 Declares a wire, with zero or more attributes, with the given identifier and options in the enclosing module.
 174
 175 See Sec.~\ref{sec:rtlil_cell_wire} for an overview of wires.
 176
 177 \begin{indentgrammar}{<wire-option>}
 178 <wire> ::= <attr-stmt>$*$ <wire-stmt>
 179
 180 <wire-stmt> ::= "wire" <wire-option>$*$ <wire-id> <eol>
 181
 182 <wire-id> ::= <id>
 183
 184 <wire-option> ::=
 185 "width" <integer>
 186   \alt "offset" <integer>
 187   \alt "input" <integer>
 188   \alt "output" <integer>
 189   \alt "inout" <integer>
 190   \alt "upto"
 191   \alt "signed"
 192 \end{indentgrammar}
 193
 194 \subsection{Memories}
 195
 196 Declares a memory, with zero or more attributes, with the given identifier and options in the enclosing module.
 197
 198 See Sec.~\ref{sec:rtlil_memory} for an overview of memory cells, and Sec.~\ref{sec:memcells} for details about memory cell types.
 199
 200 \begin{indentgrammar}{<memory-option>}
 201 <memory> ::= <attr-stmt>$*$ <memory-stmt>
 202
 203 <memory-stmt> ::= "memory" <memory-option>$*$ <id> <eol>
 204
 205 <memory-option> ::=
 206 "width" <integer>
 207   \alt "size" <integer>
 208   \alt "offset" <integer>
 209 \end{indentgrammar}
 210
 211 \subsection{Cells}
 212
 213 Declares a cell, with zero or more attributes, with the given identifier and type in the enclosing module.
 214
 215 Cells perform functions on input signals. See Chap.~\ref{chapter:celllib} for a detailed list of cell types.
 216
 217 \begin{indentgrammar}{<cell-body-stmt>}
 218 <cell> ::= <attr-stmt>$*$ <cell-stmt> <cell-body-stmt>$*$ <cell-end-stmt>
 219
 220 <cell-stmt> ::= "cell" <cell-type> <cell-id> <eol>
 221
 222 <cell-id> ::= <id>
 223
 224 <cell-type> ::= <id>
 225
 226 <cell-body-stmt> ::=
 227 "parameter" ("signed" | "real")$?$ <id> <constant> <eol>
 228   \alt "connect" <id> <sigspec> <eol>
 229
 230 <cell-end-stmt> ::= "end" <eol>
 231 \end{indentgrammar}
 232
 233 \subsection{Processes}
 234
 235 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.
 236
 237 See Sec.~\ref{sec:rtlil_process} for an overview of processes.
 238
 239 \begin{indentgrammar}{<switch-end-stmt>}
 240 <process> ::= <attr-stmt>$*$ <proc-stmt> <process-body> <proc-end-stmt>
 241
 242 <proc-stmt> ::= "process" <id> <eol>
 243
 244 <process-body> ::= <assign-stmt>$*$ <switch>$?$ <assign-stmt>$*$ <sync>$*$
 245
 246 <assign-stmt> ::= "assign" <dest-sigspec> <src-sigspec> <eol>
 247
 248 <dest-sigspec> ::= <sigspec>
 249
 250 <src-sigspec> ::= <sigspec>
 251
 252 <proc-end-stmt> ::= "end" <eol>
 253
 254 \end{indentgrammar}
 255
 256 \subsection{Switches}
 257
 258 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.
 259
 260 \begin{indentgrammar}{<switch-end-stmt>}
 261 <switch> ::= <switch-stmt> <case>$*$ <switch-end-stmt>
 262
 263 <switch-stmt> := <attr-stmt>$*$ "switch" <sigspec> <eol>
 264
 265 <case> ::= <attr-stmt>$*$ <case-stmt> <case-body>
 266
 267 <case-stmt> ::= "case" <compare>$?$ <eol>
 268
 269 <compare> ::= <sigspec> ("," <sigspec>)$*$
 270
 271 <case-body> ::= (<switch> | <assign-stmt>)$*$
 272
 273 <switch-end-stmt> ::= "end" <eol>
 274 \end{indentgrammar}
 275
 276 \subsection{Syncs}
 277
 278 Syncs update signals with other signals when an event happens. Such an event may be:
 279
 280 \begin{itemize}
 281   \item An edge or level on a signal
 282   \item Global clock ticks
 283   \item Initialization
 284   \item Always
 285 \end{itemize}
 286
 287 \begin{indentgrammar}{<dest-sigspec>}
 288 <sync> ::= <sync-stmt> <update-stmt>$*$
 289
 290 <sync-stmt> ::=
 291 "sync" <sync-type> <sigspec> <eol>
 292   \alt "sync" "global" <eol>
 293   \alt "sync" "init" <eol>
 294   \alt "sync" "always" <eol>
 295
 296 <sync-type> ::= "low" | "high" | "posedge" | "negedge" | "edge"
 297
 298 <update-stmt> ::= "update" <dest-sigspec> <src-sigspec> <eol>
 299 \end{indentgrammar}