From 6e5721442c067829ad1e5d0c2c5c52f4056c83b7 Mon Sep 17 00:00:00 2001 From: Schuyler Eldridge Date: Wed, 6 May 2020 12:35:24 -0400 Subject: Clarify indentation in spec Co-authored-by: Schuyler Eldridge Co-authored-by: Albert Magyar Signed-off-by: Schuyler Eldridge --- spec/spec.tex | 47 +++++++++++++++++++++++++++++++++++++---------- 1 file changed, 37 insertions(+), 10 deletions(-) diff --git a/spec/spec.tex b/spec/spec.tex index 1a1c99f8..9645e137 100644 --- a/spec/spec.tex +++ b/spec/spec.tex @@ -1922,18 +1922,45 @@ An integer literal in FIRRTL begins with one of the following, where `\#' repres Comments begin with a semicolon and extend until the end of the line. Commas are treated as whitespace, and may be used by the user for clarity if desired. -Block structuring is indicated using indentation. Statements are combined into statement groups by surrounding them with parenthesis. A colon at the {\em end of a line} will automatically surround the next indented region with parenthesis and thus create a statement group. +In FIRRTL, indentation is significant. +Indentation must consist of spaces only---tabs are illegal characters. +The number of spaces appearing before a FIRRTL IR statement is used to establish its \emph{indent level}. +Statements with the same indent level have the same context. +The indent level of the \verb|circuit| declaration must be zero. + +Certain constructs (\verb|circuit|, \verb|module|, \verb|when|, and \verb|else|) create a new sub-context. +The indent used on the first line of the sub-context establishes the indent level. +The indent level of a sub-context is one higher than the parent. +All statements in the sub-context must be indented by the same number of spaces. +To end the sub-context, a line must return to the indent level of the parent. + +Since conditional statements (\verb|when| and \verb|else|) may be nested, it is possible to create a hierarchy of indent levels, each with its own number of preceding spaces that must be larger than its parent’s and consistent among all direct child statements (those that are not children of an even deeper conditional statement). + +As a concrete guide, a few consequences of these rules are summarized below: + +\begin{itemize} +\item The \verb|circuit| keyword must not be indented. +\item All \verb|module| keywords must be indented by the same number of spaces. +\item In a module, all port declarations and all statements (that are not children of other statements) must be indented by the same number of spaces. +\item The number of spaces comprising the indent level of a module is specific to each module. +\item The statements comprising a conditional statement's branch must be indented by the same number of spaces. +\item The statements of nested conditional statements establish their own, deeper indent level. +\item Each \verb|when| and each \verb|else| context may have a different number of non-zero spaces in its indent level. +\end{itemize} + +As an example illustrating some of these points, the following is a legal FIRRTL circuit: -The following statement: -\begin{lstlisting} -when c : - a <= b -else : - e <= f -\end{lstlisting} -can be equivalently expressed on a single line as follows. \begin{lstlisting} -when c : a <= b else : e <= f +circuit Foo : + module Foo : + skip + module Bar : + input a: UInt<1> + output b: UInt<1> + when a: + b <= a + else: + b <= not(a) \end{lstlisting} All circuits, modules, ports and statements can optionally be followed with the info token \verb|@[fileinfo]| where fileinfo is a string containing the source file information from where it was generated. -- cgit v1.2.3 From 21cf4cfa4bcf1d5febe5efd791633c8ea0185c6a Mon Sep 17 00:00:00 2001 From: Schuyler Eldridge Date: Wed, 6 May 2020 12:35:48 -0400 Subject: Clarify spec indentation of when/else Signed-off-by: Schuyler Eldridge --- spec/spec.tex | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/spec/spec.tex b/spec/spec.tex index 9645e137..682c76a0 100644 --- a/spec/spec.tex +++ b/spec/spec.tex @@ -712,6 +712,30 @@ module MyModule : x <= d \end{lstlisting} +To additionally aid readability, a conditional statement where the contents of the \verb|when| branch consist of a single line may be combined into a single line. +If an \verb|else| branch exists, then the \verb|else| keyword must be included on the same line. + +The following statement: +\begin{lstlisting} +when c : + a <= b +else : + e <= f +\end{lstlisting} + +can have the \verb|when| keyword, the \verb|when| branch, and the \verb|else| keyword expressed as a single line: + +\begin{lstlisting} +when c : a <= b else : + e <= f +\end{lstlisting} + +The \verb|else| branch may also be added to the single line: + +\begin{lstlisting} +when c : a <= b else : e <= f +\end{lstlisting} + \subsubsection{Nested Declarations} If a component is declared within a conditional statement, connections to the component are unaffected by the condition. In the following example, register \verb|myreg1| is always connected to \verb|a|, and register \verb|myreg2| is always connected to \verb|b|. -- cgit v1.2.3 From bb6b30e4df90e22ad7e987345208330c5c6e44ed Mon Sep 17 00:00:00 2001 From: Schuyler Eldridge Date: Wed, 6 May 2020 12:36:17 -0400 Subject: Update spec.pdf Signed-off-by: Schuyler Eldridge --- spec/spec.pdf | Bin 320068 -> 323280 bytes 1 file changed, 0 insertions(+), 0 deletions(-) diff --git a/spec/spec.pdf b/spec/spec.pdf index 3f36f423..bb456a88 100644 Binary files a/spec/spec.pdf and b/spec/spec.pdf differ -- cgit v1.2.3