From 290317a9796d8f42c5f4f1cc5b4714e6897d80ad Mon Sep 17 00:00:00 2001
From: Nao Pross <np@0hm.ch>
Date: Sat, 22 May 2021 01:08:34 +0200
Subject: Start testing

---
 tex/docmacros.sty     |  7 ++++
 tex/statemachines.tex | 12 +++----
 tex/testbench.tex     | 99 +++++++++++++++++++++++++++++++++++++++++++++++++++
 tex/vhdl.tex          | 15 +++-----
 4 files changed, 116 insertions(+), 17 deletions(-)
 create mode 100644 tex/docmacros.sty
 create mode 100644 tex/testbench.tex

(limited to 'tex')

diff --git a/tex/docmacros.sty b/tex/docmacros.sty
new file mode 100644
index 0000000..9fc0325
--- /dev/null
+++ b/tex/docmacros.sty
@@ -0,0 +1,7 @@
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{docmacros}[2021/05/22 v0.1 Document Macros]
+
+\newcommand{\ph}[1]{\textrm{\textit{#1}}}
+\newcommand{\reqph}[1]{\textrm{\textlangle\,\ph{#1}\,\textrangle}}
+\newcommand{\optionalph}[1]{\textrm{[\,\ph{#1}\,]}}
+\newcommand{\vhdl}[1]{\lstinline[language=vhdl]{#1}}
diff --git a/tex/statemachines.tex b/tex/statemachines.tex
index 9fb47e2..967737b 100644
--- a/tex/statemachines.tex
+++ b/tex/statemachines.tex
@@ -1,5 +1,4 @@
 \section{State Machines}
-There are 3 types of state machines.
 \begin{figure}[h]
   \centering
   \ttfamily
@@ -65,21 +64,20 @@ There are 3 types of state machines.
 \end{figure}
 
 \subsection{Encoding the state}
-This is typical for Mealey and Moore machines.
+For Mealey and Moore machines it is typical to write:
 \begin{lstlisting}[language=vhdl]
 type state_type is (st_rst, st_a, st_b, st_c, ...);
 signal present_state, next_state : state_type;
 \end{lstlisting}
-The encoding of the state is left automatically to the synthesizer or
-configured in the graphical interface of the tool.  If a custom encoding is
-required (Medwedjew), adding the following generates a custom encoding.
+The encoding of the state is left to the synthesizer or can be configured in
+the graphical interface of the tool.  If a custom encoding is required
+(Medwedjew), adding the following generates a custom encoding.
 \begin{lstlisting}[language=vhdl]
 attribute enum_encoding : string;
 attribute enum_encoding of state_type:
   type is "0001 0010 0100 ...";
 \end{lstlisting}
-
-Or alternatively a completely different approach is using a vector type.
+Or an equivalent approach is to use a vector subtype and constants.
 \begin{lstlisting}[language=vhdl]
 subtype state_type is bit_vector(3 downto 0);
 
diff --git a/tex/testbench.tex b/tex/testbench.tex
new file mode 100644
index 0000000..b555feb
--- /dev/null
+++ b/tex/testbench.tex
@@ -0,0 +1,99 @@
+\section{Testing}
+To simulate a digial circuit it is possible to write test benches using VHDL.
+The code in this section may no longer be synthetisable, and is usually
+written by a \emph{test designer}.
+
+\subsection{Simulator}
+VHDL simulates digital systems using \emph{delta cycles}.
+%% TODO: notes on how delta cycles work
+
+\subsection{Transport delay}
+To model a time delay of a signal there are two ways:
+\begin{lstlisting}[language=vhdl]
+y <= transport `\reqph{expression}` after `\reqph{time}`;
+y <= inertial `\reqph{expression}` after `\reqph{time}`;
+\end{lstlisting}
+When \vhdl{transport} is used, the output changes only exactly after the
+specified time, the simulator simply waits. With \vhdl{inertial}, the output is
+also delayed, but only if the input lasts more than the specified time.  This
+means that for example with a time of \vhdl{10 ns} a pulse of \vhdl{5 ns} will
+be ignored. This is much more typical and realistic, thus when unspecified,
+\vhdl{after} is interpreted as \vhdl{inertial ... after}.
+\begin{lstlisting}[language=vhdl]
+y <= `\reqph{expression}` after `\reqph{time}`;
+\end{lstlisting}
+
+\subsection{Generate stimuli}
+Simple stimuli (signals) are generated using processes. For example a clock
+signal done in three ways:
+\begin{lstlisting}[language=vhdl]
+-- declaration
+constant f : integer := 1000;
+constant T : time    := 1 sec/f;
+signal clk0, clk1, clk2 : std_ulogic;
+\end{lstlisting}
+\begin{lstlisting}[language=vhdl]
+-- concurrent
+clock0: process
+begin
+  clk <= '1'; wait for (T/2);
+  clk <= '0'; wait for (T/2);
+end process;
+
+clock1: process
+begin
+  clk1 <= '1';
+  loop
+    wait for (T/2);
+    clk1 <= not clk1;
+  end loop;
+end process;
+
+-- lazy way
+clock2: clk2 <= not clk2 after (T/2);
+\end{lstlisting}
+One time stimuli can be modelled using the following expression. Note that the
+time is absolute.
+\begin{lstlisting}[language=vhdl]
+tb_sig <= '0',
+  '1' after 20 ns,
+  '0' after 30 ns, -- 10 ns later
+  `\reqph{value}` after `\reqph{time}`;
+\end{lstlisting}
+Repeating sequences can be created using processes.
+\begin{lstlisting}[language=vhdl]
+sequence: process
+begin
+  tb_sig <= '0';
+  wait for 20 ns;
+  tb_sig <= '1';
+  wait for 10 ns;
+  ...
+end process;
+\end{lstlisting}
+For loops are also available, and can be synthesised if they run over a finite
+range.
+\begin{lstlisting}[language=vhdl]
+`\optionalph{label}:` for `\reqph{parameter}` in `\reqph{range}` loop
+  -- sequentail statements
+end loop `\optionalph{label}`;
+\end{lstlisting}
+A concrete example:
+\begin{lstlisting}[language=vhdl]
+-- declaration
+constant n : integer := 3;
+signal a, b : std_ulogic_vector(n-1 downto 0);
+\end{lstlisting}
+\begin{lstlisting}[language=vhdl]
+-- sequential
+for i in 0 to 2**n -1 loop
+  a <= std_ulogic_vector(
+            to_unsigned(i, n));
+  for k in 0 to 2**n - 1 loop
+    b <= std_ulogic_vector(
+              to_unsigned(k, n));
+  end loop;
+end loop;
+\end{lstlisting}
+
+\subsection{Assertions}
diff --git a/tex/vhdl.tex b/tex/vhdl.tex
index e51b357..4674f4a 100644
--- a/tex/vhdl.tex
+++ b/tex/vhdl.tex
@@ -4,12 +4,6 @@
   % Hardware Description Language
 }
 
-\newcommand{\ph}[1]{\textrm{\textit{#1}}}
-\newcommand{\reqph}[1]{\textrm{\textlangle\,\ph{#1}\,\textrangle}}
-\newcommand{\optionalph}[1]{\textrm{[\,\ph{#1}\,]}}
-
-\newcommand{\vhdl}[1]{\lstinline[language=vhdl]{#1}}
-
 \subsection{Basic syntax and identifiers}
 In VHDL an identifier is a case insensitive string composed of
 \texttt{A-Z a-z 0-9 \_} that
@@ -67,9 +61,10 @@ an \emph{architecture}. There can be multiple architectures for a single entity.
 \end{center}
 
 Entities are declared with \vhdl{port()} that may contain a list of pins. Pins
-have a mode that can be \vhdl{in} input (only LHS), \vhdl{out} output (only
-RHS), \vhdl{inout} bidirectional or \vhdl{buffer} that can stay both on LHS and
-RHS. The usage of the latter is discourareged in favour of an internal signal.
+have a mode that can be \vhdl{in} input (only LHS\footnote{Left hand side}),
+\vhdl{out} output (only RHS\footnote{Right hand side}), \vhdl{inout}
+bidirectional or \vhdl{buffer} that can stay both on LHS and RHS. The usage of
+the latter is discourareged in favour of an internal signal.
 \begin{lstlisting}[language=vhdl]
 entity `\reqph{name}` is
   port(
@@ -291,7 +286,7 @@ u1: flipflop
 
 \subsubsection{Processes}
 For more sophisticated logic VHDL offers a way of writing sequential statements
-called \emph{processes}.
+called \emph{process}.
 \begin{lstlisting}[language=vhdl]
 `\optionalph{label}:` process (`\optionalph{sensitivity list}`)
 -- declarations
-- 
cgit v1.2.1