From 1034422c58f8a10390eb3538c2dbe6d52931bf8a Mon Sep 17 00:00:00 2001 From: Robert Baruch Date: Sun, 22 Nov 2020 12:56:29 -0800 Subject: [PATCH 01/12] Adds appendix on RTLIL text format --- manual/CHAPTER_Overview.tex | 4 + manual/CHAPTER_TextRtlil.tex | 252 +++++++++++++++++++++++++++++++++++ manual/manual.tex | 4 + 3 files changed, 260 insertions(+) create mode 100644 manual/CHAPTER_TextRtlil.tex diff --git a/manual/CHAPTER_Overview.tex b/manual/CHAPTER_Overview.tex index ed8b4cd49..83db5aac7 100644 --- a/manual/CHAPTER_Overview.tex +++ b/manual/CHAPTER_Overview.tex @@ -230,6 +230,7 @@ generated twice. For modules with only a few parameters, a name directly contain is generated instead of a hash string.) \subsection{RTLIL::Cell and RTLIL::Wire} +\label{sec:rtlil_cell_wire} A module contains zero to many RTLIL::Cell and RTLIL::Wire objects. Objects of these types are used to model netlists. Usually the goal of all synthesis efforts is to convert @@ -275,6 +276,7 @@ The connections of ports to wires are coded by assigning an RTLIL::SigSpec to each cell port. The RTLIL::SigSpec data type is described in the next section. \subsection{RTLIL::SigSpec} +\label{sec:rtlil_sigspec} A ``signal'' is everything that can be applied to a cell port. I.e. @@ -295,6 +297,7 @@ RTLIL::SigSpec objects. Such pairs are needed in different locations. Therefore the type name RTLIL::SigSig was defined for such a pair. \subsection{RTLIL::Process} +\label{sec:rtlil_process} When a high-level HDL frontend processes behavioural code it splits it up into data path logic (e.g.~the expression {\tt a + b} is replaced by the output of an @@ -444,6 +447,7 @@ pass calls a series of other passes that together perform this conversion in a w for most synthesis tasks. \subsection{RTLIL::Memory} +\label{sec:rtlil_memory} For every array (memory) in the HDL code an RTLIL::Memory object is created. A memory object has the following properties: diff --git a/manual/CHAPTER_TextRtlil.tex b/manual/CHAPTER_TextRtlil.tex new file mode 100644 index 000000000..662e5d751 --- /dev/null +++ b/manual/CHAPTER_TextRtlil.tex @@ -0,0 +1,252 @@ +\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. For example, processes must contain exactly one switch statement, but the grammar allows zero or more than one. 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, and is somewhat less understandable than simple EBNF notation. + +\section{Lexical elements} + +\subsection{Identifiers} + +There are three types of identifiers in RTLIL: + +\begin{itemize} + \item Publically visible identifiers + \item Auto-generated identifiers + \item Dotted numeric 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 + \item \texttt{z}: A high-impedance value + \item \texttt{m}: ? + \item \texttt{-}: A don't care value +\end{itemize} + +An \textit{integer} is simply a signed integer value in decimal format. + +\begin{indentgrammar}{} + ::= $+$ \texttt{\textbf{'}} $*$ + + ::= "0" | "1" | "x" | "z" | "m" | "-" + + ::= "-"$?$ $+$ +\end{indentgrammar} + +\subsection{Strings} + +A string is a series of characters delimited by double-quote characters. Within a string, 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 zero or more designs. A design may be a module, an attribute statement, or an autoindex statement. + +Note that in general, statements are terminated by an end of line. + +\begin{indentgrammar}{} + ::= $*$ + + ::= | | +\end{indentgrammar} + +\subsection{Modules} + +A module consists of zero or more module statements. + +\begin{indentgrammar}{} + ::= "module" $*$ + + ::= + + \alt + \alt + \alt + \alt + \alt + \alt +\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. + +See Sec.~\ref{sec:rtlil_sigspec} for an overview of signal specifications. + +\begin{indentgrammar}{} + ::= + + \alt + \alt "[" (":" )$?$ "]" + \alt "\{" $*$ "\}" +\end{indentgrammar} + +\subsection{Connection statements} + +Declares a connection between the given signals. + +\begin{indentgrammar}{} + ::= "connect" +\end{indentgrammar} + +\subsection{Attribute statements} + +Declares an attribute with the given identifier and value for the following non-attribute statement. + +\begin{indentgrammar}{} + ::= "attribute" + + ::= | | +\end{indentgrammar} + +\subsection{Autoindex statements} + +The function of this statement is currently undocumented. + +\begin{indentgrammar}{} + ::= "autoidx" +\end{indentgrammar} + +\subsection{Parameter statements} + +Declares a parameter with the given identifier for the enclosing module, optionally with the given default value. + +\begin{indentgrammar}{} + ::= "parameter" $?$ +\end{indentgrammar} + +\subsection{Wire statements} + +Declares a wire with the given identifier in the enclosing module, with options. + +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{Memory statements} + +Declares a memory with the given identifier in the enclosing module, with options. + +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{Cell statements} + +Declares a cell with the given identifier in the enclosing module. + +See Chap.~\ref{chapter:celllib} for a detailed list of cell types. + +\begin{indentgrammar}{} + ::= "cell" "end" + + ::= + + ::= + + ::= +"parameter" ("signed" | "real")$?$ + \alt "connect" +\end{indentgrammar} + +\subsection{Process statements} + +Declares a process with the given identifier in the enclosing module. + +See Sec.~\ref{sec:rtlil_process} for an overview of processes. + +\begin{indentgrammar}{} + ::= "process" $*$ $*$ "end" + + ::= | | + + ::= "switch" $*$ $*$ "end" + + ::= "case" $?$ $*$ + + ::= ("," )$*$ + + ::= +"sync" $*$ + \alt "sync" "always" $*$ + \alt "sync" "global" $*$ + \alt "sync" "init" $*$ + + ::= "low" | "high" | "posedge" | "negedge" | "edge" + + ::= "assign" + + ::= "update" + + ::= + + ::= +\end{indentgrammar} + diff --git a/manual/manual.tex b/manual/manual.tex index 75f087eca..dac8b1000 100644 --- a/manual/manual.tex +++ b/manual/manual.tex @@ -75,6 +75,9 @@ bookmarksopen=false% \usetikzlibrary{through} \usetikzlibrary{shapes.geometric} +\usepackage{calc} +\usepackage[nounderscore]{syntax} + \lstset{basicstyle=\ttfamily} \def\B#1{{\tt\textbackslash{}#1}} @@ -214,6 +217,7 @@ YOSYS & Yosys Open SYnthesis Suite \\ \label{commandref} \input{command-reference-manual} +\include{CHAPTER_TextRtlil} \include{CHAPTER_Appnotes} % \include{CHAPTER_StateOfTheArt} From 5159dda826e7acfc66920a72326e5ce0f3b61f71 Mon Sep 17 00:00:00 2001 From: Robert Baruch Date: Sun, 22 Nov 2020 18:48:21 -0800 Subject: [PATCH 02/12] Update to Values section --- manual/CHAPTER_TextRtlil.tex | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/manual/CHAPTER_TextRtlil.tex b/manual/CHAPTER_TextRtlil.tex index 662e5d751..6b0572c64 100644 --- a/manual/CHAPTER_TextRtlil.tex +++ b/manual/CHAPTER_TextRtlil.tex @@ -48,8 +48,8 @@ A \textit{value} consists of a width in bits and a bit representation, most sign \item \texttt{0}: A logic zero value \item \texttt{1}: A logic one value \item \texttt{x}: An unknown logic value - \item \texttt{z}: A high-impedance value - \item \texttt{m}: ? + \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} From c5a2ae01cd6b7d5f59b627eae7779359737bb847 Mon Sep 17 00:00:00 2001 From: Robert Baruch Date: Sun, 22 Nov 2020 18:50:41 -0800 Subject: [PATCH 03/12] Update to Values #2 --- manual/CHAPTER_TextRtlil.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/manual/CHAPTER_TextRtlil.tex b/manual/CHAPTER_TextRtlil.tex index 6b0572c64..30ddaafd3 100644 --- a/manual/CHAPTER_TextRtlil.tex +++ b/manual/CHAPTER_TextRtlil.tex @@ -47,7 +47,7 @@ A \textit{value} consists of a width in bits and a bit representation, most sign \begin{itemize} \item \texttt{0}: A logic zero value \item \texttt{1}: A logic one value - \item \texttt{x}: An unknown logic 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 From d3d28e287f1935a25e288ecdbb50060bc4d0de84 Mon Sep 17 00:00:00 2001 From: Robert Baruch Date: Sun, 22 Nov 2020 21:08:58 -0800 Subject: [PATCH 04/12] Adds missing "end" and eol to module. --- manual/CHAPTER_TextRtlil.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/manual/CHAPTER_TextRtlil.tex b/manual/CHAPTER_TextRtlil.tex index 30ddaafd3..e84235398 100644 --- a/manual/CHAPTER_TextRtlil.tex +++ b/manual/CHAPTER_TextRtlil.tex @@ -102,7 +102,7 @@ Note that in general, statements are terminated by an end of line. A module consists of zero or more module statements. \begin{indentgrammar}{} - ::= "module" $*$ + ::= "module" $*$ "end" ::= From 278b54227339099faf93301cfd4a6b566651441b Mon Sep 17 00:00:00 2001 From: Robert Baruch Date: Tue, 24 Nov 2020 15:27:30 -0800 Subject: [PATCH 05/12] Cleans up some descriptions and syntax Now all rules ending in "-stmt" end in eol. --- manual/CHAPTER_TextRtlil.tex | 68 +++++++++++++++++++++++------------- 1 file changed, 43 insertions(+), 25 deletions(-) diff --git a/manual/CHAPTER_TextRtlil.tex b/manual/CHAPTER_TextRtlil.tex index e84235398..720fe8fa1 100644 --- a/manual/CHAPTER_TextRtlil.tex +++ b/manual/CHAPTER_TextRtlil.tex @@ -87,33 +87,35 @@ A comment starts with a \texttt{\textbf{\#}} character and proceeds to the end o \section{File} -A file consists of zero or more designs. A design may be a module, an attribute statement, or an autoindex statement. +A file consists of zero or more modules, attribute statements, and auto-index statements. All statements terminate in an end-of-line. Because of this, statements cannot contain end-of-lines. -Note that in general, statements are terminated by an end of line. +Attributes at the file level are applied to the following module. \begin{indentgrammar}{} - ::= $*$ - - ::= | | + ::= ( | | )$*$ \end{indentgrammar} \subsection{Modules} -A module consists of zero or more module statements. +Declares a module consisting of zero or more attributes, wires, memories, cells, processes, and connections. -\begin{indentgrammar}{} - ::= "module" $*$ "end" +\begin{indentgrammar}{} + ::= - ::= - + ::= "module" + + ::= +( \alt \alt \alt - \alt - \alt - \alt + \alt + \alt + \alt )$*$ \end{indentgrammar} + ::= "end" + \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. @@ -138,7 +140,7 @@ Declares a connection between the given signals. \subsection{Attribute statements} -Declares an attribute with the given identifier and value for the following non-attribute statement. +Declares an attribute with the given identifier and value. Attributes at the file level apply to the following module. Attributes within a module apply to the following non-attribute statement. \begin{indentgrammar}{} ::= "attribute" @@ -198,14 +200,16 @@ See Sec.~\ref{sec:rtlil_memory} for an overview of memory cells, and Sec.~\ref{s \alt "offset" \end{indentgrammar} -\subsection{Cell statements} +\subsection{Cells} Declares a cell with the given identifier in the enclosing module. See Chap.~\ref{chapter:celllib} for a detailed list of cell types. \begin{indentgrammar}{} - ::= "cell" "end" + ::= + + ::= "cell" ::= @@ -214,6 +218,8 @@ See Chap.~\ref{chapter:celllib} for a detailed list of cell types. ::= "parameter" ("signed" | "real")$?$ \alt "connect" + + ::= "end" \end{indentgrammar} \subsection{Process statements} @@ -222,22 +228,34 @@ Declares a process with the given identifier in the enclosing module. See Sec.~\ref{sec:rtlil_process} for an overview of processes. -\begin{indentgrammar}{} - ::= "process" $*$ $*$ "end" +\begin{indentgrammar}{} + ::= $*$ - ::= | | + ::= "process" - ::= "switch" $*$ $*$ "end" + ::= "end" - ::= "case" $?$ $*$ + ::= ( | | )$*$ + + ::= $*$ $*$ + + := "switch" + + ::= "end" + + ::= + + ::= "case" $?$ ::= ("," )$*$ + ::= $*$ + ::= -"sync" $*$ - \alt "sync" "always" $*$ - \alt "sync" "global" $*$ - \alt "sync" "init" $*$ +"sync" + \alt "sync" "always" + \alt "sync" "global" + \alt "sync" "init" ::= "low" | "high" | "posedge" | "negedge" | "edge" From be938b309451c152aab6edb4e4745aa682a2bf39 Mon Sep 17 00:00:00 2001 From: Robert Baruch Date: Tue, 24 Nov 2020 21:59:53 -0800 Subject: [PATCH 06/12] Refactors for attributes. --- manual/CHAPTER_TextRtlil.tex | 100 +++++++++++++++++------------------ 1 file changed, 50 insertions(+), 50 deletions(-) diff --git a/manual/CHAPTER_TextRtlil.tex b/manual/CHAPTER_TextRtlil.tex index 720fe8fa1..f3962c4a4 100644 --- a/manual/CHAPTER_TextRtlil.tex +++ b/manual/CHAPTER_TextRtlil.tex @@ -19,6 +19,8 @@ The grammar is not meant to represent semantic limitations. For example, process 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, 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, statements cannot contain end-of-lines. + \section{Lexical elements} \subsection{Identifiers} @@ -87,34 +89,53 @@ A comment starts with a \texttt{\textbf{\#}} character and proceeds to the end o \section{File} -A file consists of zero or more modules, attribute statements, and auto-index statements. All statements terminate in an end-of-line. Because of this, statements cannot contain end-of-lines. - -Attributes at the file level are applied to the following module. +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 consisting of zero or more attributes, wires, memories, cells, processes, and connections. +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 \alt \alt - \alt )$*$ -\end{indentgrammar} + \alt )$*$ + + ::= "parameter" $?$ + + ::= | | ::= "end" +\end{indentgrammar} + +\subsection{Attribute statements} + +Declares an attribute with the given identifier and value. + +\textbf{Warning:} There is currently a bug where integer constants are silently truncated to 32 bits and treated as unsigned. + +\begin{indentgrammar}{} + ::= "attribute" +\end{indentgrammar} \subsection{Signal specifications} @@ -130,47 +151,25 @@ See Sec.~\ref{sec:rtlil_sigspec} for an overview of signal specifications. \alt "\{" $*$ "\}" \end{indentgrammar} -\subsection{Connection statements} +\subsection{Connections} -Declares a connection between the given signals. +Declares a connection, with zero or more attributes, between the given signals. + +\begin{indentgrammar}{} + ::= $*$ -\begin{indentgrammar}{} ::= "connect" \end{indentgrammar} -\subsection{Attribute statements} +\subsection{Wires} -Declares an attribute with the given identifier and value. Attributes at the file level apply to the following module. Attributes within a module apply to the following non-attribute statement. - -\begin{indentgrammar}{} - ::= "attribute" - - ::= | | -\end{indentgrammar} - -\subsection{Autoindex statements} - -The function of this statement is currently undocumented. - -\begin{indentgrammar}{} - ::= "autoidx" -\end{indentgrammar} - -\subsection{Parameter statements} - -Declares a parameter with the given identifier for the enclosing module, optionally with the given default value. - -\begin{indentgrammar}{} - ::= "parameter" $?$ -\end{indentgrammar} - -\subsection{Wire statements} - -Declares a wire with the given identifier in the enclosing module, with options. +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" $*$ ::= @@ -185,13 +184,15 @@ See Sec.~\ref{sec:rtlil_cell_wire} for an overview of wires. \alt "signed" \end{indentgrammar} -\subsection{Memory statements} +\subsection{Memories} -Declares a memory with the given identifier in the enclosing module, with options. +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" $*$ ::= @@ -202,12 +203,12 @@ See Sec.~\ref{sec:rtlil_memory} for an overview of memory cells, and Sec.~\ref{s \subsection{Cells} -Declares a cell with the given identifier in the enclosing module. +Declares a cell, with zero or more attributes, with the given identifier and type in the enclosing module. See Chap.~\ref{chapter:celllib} for a detailed list of cell types. \begin{indentgrammar}{} - ::= + ::= $*$ $*$ ::= "cell" @@ -222,14 +223,14 @@ See Chap.~\ref{chapter:celllib} for a detailed list of cell types. ::= "end" \end{indentgrammar} -\subsection{Process statements} +\subsection{Processes} -Declares a process with the given identifier in the enclosing module. +Declares a process, with zero or more attributes, with the given identifier in the enclosing module. See Sec.~\ref{sec:rtlil_process} for an overview of processes. \begin{indentgrammar}{} - ::= $*$ + ::= $*$ $*$ ::= "process" @@ -267,4 +268,3 @@ See Sec.~\ref{sec:rtlil_process} for an overview of processes. ::= \end{indentgrammar} - From 39af3e629f5ae1e6e2a70b64330460ea0096440d Mon Sep 17 00:00:00 2001 From: Robert Baruch Date: Wed, 25 Nov 2020 08:59:25 -0800 Subject: [PATCH 07/12] Clarifies processes, corrects some attributes --- manual/CHAPTER_TextRtlil.tex | 75 ++++++++++++++++++++++-------------- 1 file changed, 46 insertions(+), 29 deletions(-) diff --git a/manual/CHAPTER_TextRtlil.tex b/manual/CHAPTER_TextRtlil.tex index f3962c4a4..ee77a987d 100644 --- a/manual/CHAPTER_TextRtlil.tex +++ b/manual/CHAPTER_TextRtlil.tex @@ -15,22 +15,21 @@ This appendix documents the text representation of RTLIL in extended Backus-Naur form (EBNF). -The grammar is not meant to represent semantic limitations. For example, processes must contain exactly one switch statement, but the grammar allows zero or more than one. That is, the grammar is "permissive", and later stages of processing perform more rigorous checks. +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, and is somewhat less understandable than simple EBNF notation. +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, statements cannot contain end-of-lines. +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{Identifiers} -There are three types of identifiers in RTLIL: +There are two types of identifiers in RTLIL: \begin{itemize} \item Publically visible identifiers \item Auto-generated identifiers - \item Dotted numeric identifiers \end{itemize} \begin{indentgrammar}{} @@ -39,8 +38,6 @@ There are three types of identifiers in RTLIL: ::= "\textbackslash" $+$ ::= "\textdollar" $+$ - - ::= "." $+$ \end{indentgrammar} \subsection{Values} @@ -118,7 +115,7 @@ Declares a module, with zero or more attributes, consisting of zero or more wire \alt \alt \alt - \alt )$*$ + \alt )$*$ ::= "parameter" $?$ @@ -131,7 +128,7 @@ Declares a module, with zero or more attributes, consisting of zero or more wire Declares an attribute with the given identifier and value. -\textbf{Warning:} There is currently a bug where integer constants are silently truncated to 32 bits and treated as unsigned. +\textbf{Warning:} Integer constants greater than 32 bits are silently truncated to 32 bits and treated as unsigned. \begin{indentgrammar}{} ::= "attribute" @@ -153,11 +150,9 @@ See Sec.~\ref{sec:rtlil_sigspec} for an overview of signal specifications. \subsection{Connections} -Declares a connection, with zero or more attributes, between the given signals. - -\begin{indentgrammar}{} - ::= $*$ +Declares a connection between the given signals. +\begin{indentgrammar}{} ::= "connect" \end{indentgrammar} @@ -203,9 +198,9 @@ See Sec.~\ref{sec:rtlil_memory} for an overview of memory cells, and Sec.~\ref{s \subsection{Cells} -Declares a cell, with zero or more attributes, with the given identifier and type in the enclosing module. +Declares a cell, with zero or more attributes, with the given identifier and type in the enclosing module. -See Chap.~\ref{chapter:celllib} for a detailed list of cell types. +Cells perform functions on input signals. See Chap.~\ref{chapter:celllib} for a detailed list of cell types. \begin{indentgrammar}{} ::= $*$ $*$ @@ -225,46 +220,68 @@ See Chap.~\ref{chapter:celllib} for a detailed list of cell types. \subsection{Processes} -Declares a process, with zero or more attributes, with the given identifier in the enclosing module. +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} - := "switch" +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. - ::= "end" +\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" "always" \alt "sync" "global" \alt "sync" "init" + \alt "sync" "always" ::= "low" | "high" | "posedge" | "negedge" | "edge" - ::= "assign" - ::= "update" - - ::= - - ::= \end{indentgrammar} From 09f6e9d6b6c45b164188c8cdcc75e9628e531bfa Mon Sep 17 00:00:00 2001 From: Robert Baruch Date: Wed, 25 Nov 2020 09:53:39 -0800 Subject: [PATCH 08/12] Clarifies use of integers, and character set. --- manual/CHAPTER_TextRtlil.tex | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/manual/CHAPTER_TextRtlil.tex b/manual/CHAPTER_TextRtlil.tex index ee77a987d..12b90a7f7 100644 --- a/manual/CHAPTER_TextRtlil.tex +++ b/manual/CHAPTER_TextRtlil.tex @@ -23,6 +23,10 @@ Finally, note that all statements (rules ending in \texttt{-stmt}) terminate in \section{Lexical elements} +\subsection{Characters} + +The characters accepted in an RTLIL file are those encodable in 8 bits. Unicode is not supported. For maximum safety, limit characters to the 7-bit ASCII range $[0,127]$. + \subsection{Identifiers} There are two types of identifiers in RTLIL: @@ -33,13 +37,15 @@ There are two types of identifiers in RTLIL: \end{itemize} \begin{indentgrammar}{} - ::= | | + ::= | ::= "\textbackslash" $+$ ::= "\textdollar" $+$ \end{indentgrammar} +A \texttt{nonws} character is any character other than a space (ASCII 32), tab (ASCII 9), newline (ASCII 10), or carriage return (ASCII 13). + \subsection{Values} A \textit{value} consists of a width in bits and a bit representation, most significant bit first. Bits may be any of: @@ -52,11 +58,13 @@ A \textit{value} consists of a width in bits and a bit representation, most sign \item \texttt{-}: A don't care value \end{itemize} -An \textit{integer} is simply a signed integer value in decimal format. +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" | "-" ::= "-"$?$ $+$ @@ -128,8 +136,6 @@ Declares a module, with zero or more attributes, consisting of zero or more wire Declares an attribute with the given identifier and value. -\textbf{Warning:} Integer constants greater than 32 bits are silently truncated to 32 bits and treated as unsigned. - \begin{indentgrammar}{} ::= "attribute" \end{indentgrammar} @@ -138,6 +144,8 @@ Declares an attribute with the given identifier and value. 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}{} From 5615c4190758c2df6ab55f8332a478296b6fd0af Mon Sep 17 00:00:00 2001 From: Robert Baruch Date: Wed, 25 Nov 2020 09:58:36 -0800 Subject: [PATCH 09/12] Cleans up doublequotes --- manual/CHAPTER_TextRtlil.tex | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/manual/CHAPTER_TextRtlil.tex b/manual/CHAPTER_TextRtlil.tex index 12b90a7f7..6bcb325fc 100644 --- a/manual/CHAPTER_TextRtlil.tex +++ b/manual/CHAPTER_TextRtlil.tex @@ -15,7 +15,7 @@ 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 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. @@ -84,7 +84,7 @@ All other characters may be escaped by a backslash, and become the following cha \begin{itemize} \item \texttt{\textbackslash \textbackslash}: A backslash - \item \texttt{\textbackslash \"}: A double-quote + \item \texttt{\textbackslash ''}: A double-quote \item \texttt{\textbackslash r}: An 'r' character \end{itemize} From 1faf0e6dcc734355ff8eb45d6ac63a6e8ae08f7b Mon Sep 17 00:00:00 2001 From: Robert Baruch Date: Wed, 25 Nov 2020 10:06:22 -0800 Subject: [PATCH 10/12] Clarifies whitespace and eol. --- manual/CHAPTER_TextRtlil.tex | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/manual/CHAPTER_TextRtlil.tex b/manual/CHAPTER_TextRtlil.tex index 6bcb325fc..1454bc26e 100644 --- a/manual/CHAPTER_TextRtlil.tex +++ b/manual/CHAPTER_TextRtlil.tex @@ -27,6 +27,12 @@ Finally, note that all statements (rules ending in \texttt{-stmt}) terminate in The characters accepted in an RTLIL file are those encodable in 8 bits. Unicode is not supported. For maximum safety, limit characters to the 7-bit ASCII range $[0,127]$. +Between lexer tokens outside of strings, spaces (ASCII 32) and tabs (ASCII 9) are ignored. + +A \texttt{nonws} character is any character other than a space (ASCII 32), tab (ASCII 9), newline (ASCII 10), or carriage return (ASCII 13). + +An \texttt{eol} is any number of consecutive newlines (ASCII 10) and carriage returns (ASCII 13). + \subsection{Identifiers} There are two types of identifiers in RTLIL: @@ -44,8 +50,6 @@ There are two types of identifiers in RTLIL: ::= "\textdollar" $+$ \end{indentgrammar} -A \texttt{nonws} character is any character other than a space (ASCII 32), tab (ASCII 9), newline (ASCII 10), or carriage return (ASCII 13). - \subsection{Values} A \textit{value} consists of a width in bits and a bit representation, most significant bit first. Bits may be any of: From 5d1bb79895545772703f305180e73053aec747c2 Mon Sep 17 00:00:00 2001 From: Robert Baruch Date: Wed, 25 Nov 2020 11:57:17 -0800 Subject: [PATCH 11/12] Clarifies how character encodings work. --- manual/CHAPTER_TextRtlil.tex | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/manual/CHAPTER_TextRtlil.tex b/manual/CHAPTER_TextRtlil.tex index 1454bc26e..7e7dc19ca 100644 --- a/manual/CHAPTER_TextRtlil.tex +++ b/manual/CHAPTER_TextRtlil.tex @@ -25,13 +25,13 @@ Finally, note that all statements (rules ending in \texttt{-stmt}) terminate in \subsection{Characters} -The characters accepted in an RTLIL file are those encodable in 8 bits. Unicode is not supported. For maximum safety, limit characters to the 7-bit ASCII range $[0,127]$. +The characters accepted in an RTLIL file are those encodable in 8 bits. UTF-8 is safe to use. Byte order marks at the beginning of the file will cause an error. -Between lexer tokens outside of strings, spaces (ASCII 32) and tabs (ASCII 9) are ignored. +ASCII spaces (32) and tabs (9) separate lexer tokens. -A \texttt{nonws} character is any character other than a space (ASCII 32), tab (ASCII 9), newline (ASCII 10), or carriage return (ASCII 13). +A \texttt{nonws} character, used in identifiers, is any character whose encoding consists solely of bytes above ASCII space (32). -An \texttt{eol} is any number of consecutive newlines (ASCII 10) and carriage returns (ASCII 13). +An \texttt{eol} is one or more consecutive ASCII newlines (10) and carriage returns (13). \subsection{Identifiers} @@ -76,7 +76,7 @@ An \textit{integer} is simply a signed integer value in decimal format. \textbf{ \subsection{Strings} -A string is a series of characters delimited by double-quote characters. Within a string, certain escapes can be used: +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 From 2bb3fc654a812dd2d82c6b3250a46dcede035de8 Mon Sep 17 00:00:00 2001 From: Robert Baruch Date: Wed, 25 Nov 2020 12:02:35 -0800 Subject: [PATCH 12/12] Further juggles the wording of "character". --- manual/CHAPTER_TextRtlil.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/manual/CHAPTER_TextRtlil.tex b/manual/CHAPTER_TextRtlil.tex index 7e7dc19ca..243b56a87 100644 --- a/manual/CHAPTER_TextRtlil.tex +++ b/manual/CHAPTER_TextRtlil.tex @@ -25,7 +25,7 @@ Finally, note that all statements (rules ending in \texttt{-stmt}) terminate in \subsection{Characters} -The characters accepted in an RTLIL file are those encodable in 8 bits. UTF-8 is safe to use. Byte order marks at the beginning of the file will cause an error. +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.