Sockeye TN: Complete syntax chapter
[barrelfish] / doc / 025-sockeye / Sockeye.tex
index b47f2c2..b4664ab 100644 (file)
@@ -10,6 +10,7 @@
 \providecommand{\pgfsyspdfmark}[3]{}
 
 \documentclass[a4paper,11pt,twoside]{report}
+\usepackage[T1]{fontenc}
 \usepackage{amsmath}
 \usepackage{bftn}
 \usepackage{calc}
@@ -32,7 +33,7 @@
 
 
 \lstdefinelanguage{Sockeye}{
-    morekeywords={is,are,accept,map,over,to,at},
+    morekeywords={accept, are, as, at, import, in, input, is, map, module, output, over, reserved, to, with},
     sensitive=true,
     morecomment=[l]{//},
     morecomment=[s]{/*}{*/},
@@ -180,7 +181,7 @@ module, output, over, reserved, to, with
 
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\chapter{Decoding Net }
+\chapter{Syntax}
 \label{chap:declaration}
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
@@ -188,12 +189,15 @@ In this chapter we define the layout of a Sockeye file.
 The node declarations in a Sockeye file describe a single decoding net.
 Parts of a decoding net can be packaged into reusable modules (see Section~\ref{sec:modules}).
 With imports (see Section~\ref{sec:imports}) modules can also be put into separate files.
-Also an SoC can be split into multiple decoding nets e.g. one for the address spaces and another one for the interrupt routes.
+Also, a SoC can be split into multiple decoding nets e.g. one for the address spaces and another one for the interrupt routes.
 
 In the following sections we use EBNF to specify the Sockeye syntax. Terminals are \textbf{bold} while non-terminals are \textit{italic}.
 The non-terminals \textit{iden}, \textit{letter}, \textit{decimal} and \textit{hexadecimal} correspond to the ones defined in Chapter~\ref{chap:lexer}.
 
 \section{Basic Syntax}
+This section describes the basic syntax for Sockeye.
+It closely corresponds to the concrete syntax described in \cite{achermann:mars17}.
+If there are important syntactic or semantic differences it is stated so in the description of the respective syntactical construct.
 
 \subsection{Node declarations}
 A node declaration contains one or more identifiers and the node specification.
@@ -205,15 +209,16 @@ The order in which the nodes are declared does not matter.
     \Big\{
         \textit{iden}\ \textbf{is}\ \textit{node}_s\
     \Big|\
-        \bigl\{ \textit{iden}\bigr\}\ \textbf{are}\ \textit{node}_s
+        \textit{iden}\bigl\{\textbf{,}\ \textit{iden}\bigr\}\ \textbf{are}\ \textit{node}_s
     \Big\} \\
 \end{align*}
 
+\clearpage
 \paragraph{Example}
 \begin{syntax}
     node1 \textbf{is} \ldots
 
-    node2
+    node2,
     node3 \textbf{are} \ldots
 \end{syntax}
 
@@ -222,7 +227,7 @@ A node specification consists of a type, a set of accepted address blocks, a set
 All of these are optional.
 The reserved address blocks are only relevant in conjunction with overlays and are used to exclude some addresses from the overlay.
 The overlay is specified as a node identifier and a number of address bits.
-The overlay will take effect from \texttt{0x0} to \(\texttt{0x2}^\texttt{bits} - \texttt{1}\).
+The overlay will span addresses from \texttt{0x0} to \(\texttt{0x2}^\texttt{bits} - \texttt{1}\).
 
 \paragraph{Syntax}
 \begin{align*}
@@ -243,11 +248,11 @@ The overlay will take effect from \texttt{0x0} to \(\texttt{0x2}^\texttt{bits} -
         \textit{overlay}\ 
     \Big]\\
 \textit{accept} & \mathop{=}
-    \textbf{accept [}\ \big[\ \textit{block}_s\big\{\textbf{,}\ \textit{block}_s\big\}\ \big]\ \textbf{]}\\
+    \textbf{accept [}\ \big\{\ \textit{block}_s\ \big\}\ \textbf{]}\\
 \textit{map} & \mathop{=}
-    \textbf{map [}\ \big[\ \textit{map}_s\big\{\textbf{,}\ \textit{map}_s\big\}\ \big]\ \textbf{]}\\
+    \textbf{map [}\ \big\{\ \textit{map}_s\ \big\}\ \textbf{]}\\
 \textit{reserved} & \mathop{=}
-    \textbf{reserved [}\ \big[\textit{block}_s\big\{\textbf{,}\ \textit{block}_s\big\}\ \big]\ \textbf{]}\\
+    \textbf{reserved [}\ \big\{\ \textit{block}_s\ \big\}\ \textbf{]}\\
 \textit{overlay} & \mathop{=}
     \textbf{over}\ \textit{iden}\textbf{/}\textit{decimal}\\
 \end{align*}
@@ -277,7 +282,6 @@ The \Sockeye{device}-type specifies that the accepted addresses are device regis
     node2 \textbf{is} device \textbf{accept} [\ldots]
 \end{syntax}
 
-\clearpage
 \subsection{Addresses}
 Addresses are specified as hexadecimal literals.
 
@@ -286,7 +290,7 @@ Addresses are specified as hexadecimal literals.
 \textit{addr} & \mathop{=} \textit{hexadecimal} \\
 \end{align*}
 
-\subsection{Block specification}{}
+\subsection{Block specifications}
 A block is specified by its start and end address.
 If the start and end address are the same, the end address can be omitted.
 Sockeye also supports specifying a block as its base address and the number of address bits the block spans:
@@ -298,7 +302,7 @@ A block from \Sockeye{0x0} to \Sockeye{0xFFF} with a size of 4kB can be specifie
     \Big[
         \textbf{-}\ \textit{addr}\ 
     \Big|\
-        \textbf{/}decimal
+        \textbf{/}\textit{decimal}
     \Big] \\
 \end{align*}
 
@@ -306,13 +310,13 @@ A block from \Sockeye{0x0} to \Sockeye{0xFFF} with a size of 4kB can be specifie
 \begin{syntax}
     node1 is \textbf{accept} [0x42-0x51]
     node2 is \textbf{accept} [0x42]      // \textit{same as \textup{0x42-0x42}}
-    node3 is \textbf{accept} [0x0/12]    // \textit{same as \textup{0x00-0xFFF}}
+    node3 is \textbf{accept} [0x0/12]    // \textit{same as \textup{0x0-0xFFF}}
 \end{syntax}
 
 \subsection{Map specification}
 A map specification is a source address block, a target node identifier and optionally a target base address to which the source block is translated within the target node.
 If no target base address is given, the block is translated to the target node starting at \Sockeye{0x0}.
-Note that this is different from the concrete syntax described in \cite{achermann:mars17} where unspecified base address means use the base address of the source block.
+Note that this is different from the concrete syntax described in \cite{achermann:mars17} where in this case the base address of the source block is used.
 This was changed due to the mapping to \Sockeye{0x0} being used more often in practice.
 Multiple translation targets can be specified by giving a comma-separated list of targets.
 
@@ -347,8 +351,109 @@ Multiple translation targets can be specified by giving a comma-separated list o
 
 \section{Modules}
 \label{sec:modules}
+A module encapsulates a decoding net which can be integrated into a larger decoding net.
+A module instantiation always creates a namespace inside the current one.
+Normally nodes can only be referenced by nodes in the same namespace but there needs to be away to reference nodes inside a module and also a way for nodes inside the module to reference nodes outside of it.
+This is done via ports.
+There are input ports, which create a connection into the module and output ports which create connections from the module to outside nodes.
+A port has always a width, specified as the number of address bits the port spans.
+All declared input ports must have a corresponding node declaration in the module body.
+
+When a module is instantiated a list of port mappings can be specified.
+An input port mapping creates a node outside the module that overlays the node inside the module.
+An output port mapping creates a node inside the module that overlays the node outside the module.
+Not all ports a module defines have to be mapped.
+Not mapping an input port simply means there is no connection to the corresponding node inside the module.
+For unmapped output ports there will be an empty node inside the module, which is a dead end for address resolution.
+
+Additionally a module can also be parametrized.
+It will then be a module template that only becomes a fully defined module when instantiated with concrete arguments.
+Module parameters are typed and the Sockeye compiler checks that they are used in a type safe way.
+There are two types of parameters, address parameters and natural parameters.
+Address parameters allow to parametrize addresses in node specifications.
+Natural parameters are used in combination with interval template identifiers (see Section~\ref{sec:template_idens}).
+Parameters can also be passed as arguments to module template instantiations in the module body.
+
+\subsection{Module Declarations}
+A module declaration starts with the keyword \Sockeye{module} and a unique module name.
+If the module is a template, a list of typed parameters can be specified.
+The module body is enclosed in curly braces and starts with the port definitions.
+The rest of the body are node declarations and module instantiations.
+If the module has address parameters the name of the parameter can be used wherever in the body an address is expected.
+
+\paragraph{Syntax}
+\begin{align*}
+    \textit{param\_type} & \mathop{=}
+        \textbf{addr}\ |\ \textbf{nat}\\
+    \textit{parameter} & \mathop{=}
+        \textit{param\_type}\ \textit{iden}\\
+    \textit{param\_list} & \mathop{=}
+        \textbf{(}\big[\ 
+            \textit{parameter}\big\{\textbf{,}\ \textit{parameter}\big\}\ 
+        \big] \textbf{)}\\
+    \textit{input\_port} & \mathop{=}
+        \textbf{input}\ \textit{iden}\textbf{/}\textit{decimal}
+        \big\{
+            \textbf{,}\ \textit{iden}\textbf{/}\textit{decimal}
+        \big\}\\
+    \textit{output\_port} & \mathop{=}
+        \textbf{output}\ \textit{iden}\textbf{/}\textit{decimal}
+        \big\{
+            \textbf{,}\ \textit{iden}\textbf{/}\textit{decimal}
+        \big\}\\
+    \textit{body}_s & \mathop{=}
+        \big\{\ 
+            \textit{net}_s\ |\ \textit{mod\_inst}_s\ 
+        \big\}\\
+    \textit{mod\_decl}_s & \mathop{=}
+        \textbf{module}\ \textit{iden} \big[\textit{param\_list}\big]\ 
+        \textbf{\{}\ 
+            \big\{\textit{input\_port}\ |\ \textit{output\_port}\big\}\ 
+            \textit{body}_s\ 
+        \textbf{\}}\\
+\end{align*}
+
+\subsection{Module Instantiations}
+Module instantiations start with the module name and in the case of a module template with the list of arguments.
+After that the identifier of the namespace in which to instantiate the module has to be given followed by an optional list of port mappings.
+
+\paragraph{Syntax}
+\begin{align*}
+    \textit{argument} & \mathop{=}
+        \textit{decimal}\ |\ \textit{hexadecimal}\ |\ \textit{iden}\\
+    \textit{arg\_list} & \mathop{=}
+        \textbf{(}\big[\ 
+            \textit{argument}\big\{\textbf{,}\ \textit{argument}\big\}\ 
+        \big] \textbf{)}\\
+    \textit{mod\_inst}_s & \mathop{=}
+        \textit{iden} \big[\textit{arg\_list}\big]\ \textbf{as}\ \textit{iden}\ \big[\ 
+            \textbf{with}\ \big\{\textit{input\_map}\ |\ \textit{output\_map}\big\}\ 
+        \big]\\
+    \textit{input\_map} & \mathop{=}
+        \textit{iden}\ \textbf{>}\ \textit{iden}\\
+    \textit{output\_map} & \mathop{=}
+        \textit{iden}\ \textbf{<}\ \textit{iden}\\
+\end{align*}
+
+\clearpage
+\paragraph{Example}
+\begin{syntax}
+    /* Instantiate module 'SomeModule' in namespace 'subspace' /*
+    SomeModule \textbf{as} subspace
+
+    /* Pass arguments to module template */
+    TemplModule(0x0, 42) \textbf{as} templSubspace
+
+    /* Declare port mappings:
+       - map 'Node1' to ouptut port 'Out'
+       - map input port 'In' to 'Node2' */
+    SomeModule \textbf{as} subspace \textbf{with}
+        Node1 > Out
+        Node2 < In
+\end{syntax}
 
 \section{Templated Identifiers}
+\label{sec:template_idens}
 Templated identifiers allow to declare multiple nodes and ports at once and instantiate a module multiple times at once.
 There are two forms of templated identifiers:
 \begin{description}
@@ -359,37 +464,39 @@ There are two forms of templated identifiers:
     \item[Simple template]
         Simple templates work very similar to interval templates.
         The only difference is, that a simple template can only reference index variables declared in the same context.
-        It can not contain intervals which declare new index variables.
+        It can not contain intervals to declare new index variables.
 \end{description}
 
-Interval templates can be used in identifiers of node declarations (to declare multiple nodes at once), port declarations (to declare multiple ports at once) and namespaces of module instantiations (to instantiate a module multiple times).
+Interval templates can be used in identifiers of node declarations (to declare multiple nodes), port declarations (to declare multiple ports) and namespace identifiers of module instantiations (to instantiate a module multiple times).
 The scope of index variables is the corresponding syntactic construct the interval template was used in.
 Simple templates can be used in any place a node identifier is expected.
+This includes the places where interval templates can be used, translation destination node identifiers and overlays but not module parameter or index variable names.
 
 An important thing to note is that the limits of an interval can reference module parameters of type \Sockeye{nat}.
-This allows module parameters to control the number of certain nodes in a module declaration.
+This allows module parameters to control how many ports or nodes are instantiated from a certain interval template.
 
 \paragraph{Syntax}
 \begin{align*}
+    \textit{var} & \mathop{=}
+        \textit{iden}\\
     \textit{limit} & \mathop{=}
         \textit{decimal}\ |\ \textit{iden} \\
-    \textit{interval}_s & \mathop{=}
+    \textit{interval} & \mathop{=}
         \textbf{[}\textit{limit}\textbf{..}\textit{limit}\textbf{]}\\
-    \textit{for\_iden}_s & \mathop{=}
-        \textit{iden}\textbf{\{}\textit{var}\ \textbf{in}\ \textit{interval}_s\textbf{\}}
+    \textit{interval\_templ}_s & \mathop{=}
+        \textit{iden}\textbf{\{}\textit{var}\ \textbf{in}\ \textit{interval}\textbf{\}}
         \Big[
             \textit{iden}\ |\ \textit{templ\_iden}_s\ |\ \textit{for\_iden}_s
         \Big]\\
-    \textit{var} & \mathop{=}
-        \textit{iden}\\
-    \textit{templ\_iden}_s & \mathop{=}
+    \textit{simple\_templ}_s & \mathop{=}
         \textit{iden}\textbf{\{}\textit{var}\textbf{\}}\Big[\textit{iden}\ |\ \textit{templ\_iden}_s\Big]\\
 \end{align*}
 
 \paragraph{Example}
 \begin{syntax}
     /* Declare similar nodes
-       (Note that interval templates always require the usage of 'are' */
+       (Note that interval templates in node declarations
+       always require the usage of '\textbf{are}') */
     Device_\verb+{+[1..5]\verb+}+ \textbf{are} device \textbf{accept} [0x0/8]
 
     /* Use the index in the node definition */
@@ -403,7 +510,7 @@ This allows module parameters to control the number of certain nodes in a module
     \verb+}+
 
     /* Instantiate module multiple times
-       and use index variable in port mappings*/
+       and use index variable in port mappings */
     SomeModule(3) \textbf{as} sub_module_\verb+{+m in [1..2]\verb+}+ \textbf{with}
         Node_\verb+{+m\verb+}+_\verb+{+o in [1..3]\verb+}+ > Out_\verb+{+o\verb+}+
 \end{syntax}
@@ -425,8 +532,8 @@ The compiler will first look for files in the current directory and then check t
 
 \paragraph{Example}
 \begin{syntax}
-    /* Invoked with 'sockeye -i imports -i modules' this will cause
-       the compiler to look for the files
+    /* Invoked with 'sockeye -i imports -i modules' the following
+       will cause the compiler to look for the files
        - ./subdir/core.soc
        - imports/subdir/core.soc
        - modules/subdir/core.soc
@@ -434,14 +541,30 @@ The compiler will first look for files in the current directory and then check t
     \textbf{import} subdir/core
 \end{syntax}
 
-\clearpage
-\section{Example Specification}
-Listing~\ref{lst:sockeye_example} shows an example Sockeye specification.
+\section{Sockeye Files}
+A sockeye file consists of imports, module declarations and the specification body (node declarations and module instantiations).
 
-\lstinputlisting[caption={Example Sockeye specification}, label={lst:sockeye_example}, language=Sockeye]{example.soc}
+\paragraph{Syntax}
+\begin{align*}
+    \textit{sockeye}_s & \mathop{=}
+        \big\{\ 
+            \textit{import}_s\ 
+        \big\}\ 
+        \big\{\ 
+            \textit{mod\_decl}_s\ 
+        \big\}\ 
+        \big\{\ 
+            \textit{net}_s\ |\ \textit{mod\_inst}_s\ 
+        \big\}
+\end{align*}
 
+\paragraph{Example}
+Listing~\ref{lst:sockeye_example} shows an example Sockeye specification.
 The specification for the Texas Instruments OMAP4460 SoC used on the PandaboardES can serve as a real world example. It is located in \pathname{SOURCE/socs/omap44xx.soc}.
 
+\clearpage
+\lstinputlisting[caption={Example Sockeye specification}, label={lst:sockeye_example}, language=Sockeye]{example.soc}
+
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \chapter{Checks on the AST}