%$Id: u.tex,v 25.95 2006/08/26 01:26:53 al Exp $ -*- LaTeX -*-
% man circuit u .
% Copyright (C) 2001 Albert Davis
% Author: Albert Davis <aldavis@ieee.org>
%
% This file is part of "Gnucap", the Gnu Circuit Analysis Package
%
% This program is free software; you can redistribute it and/or modify
% it under the terms of the GNU General Public License as published by
% the Free Software Foundation; either version 2, or (at your option)
% any later version.
%
% This program is distributed in the hope that it will be useful,
% but WITHOUT ANY WARRANTY; without even the implied warranty of
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
% GNU General Public License for more details.
%
% You should have received a copy of the GNU General Public License
% along with this program; if not, write to the Free Software
% Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
% 02110-1301, USA.
%------------------------------------------------------------------------
\section{{\tt U}: Logic Device}
%------------------------------------------------------------------------
\subsection{Syntax}
\subsubsection{Device}
\begin{verse}
{\tt U}{\it xxxxxxx} {\it out gnd vdd enable in1 in2 ... family gatetype}
\end{verse}
\subsubsection{Model (required)}
\begin{verse}
{\tt .model} {\it mname} {\tt LOGIC} \{{\it args}\}
\end{verse}
\subsubsection{Subcircuit definition (optional)}
\begin{verse}
{\tt .subckt} {\it subname} {\it nodes}\\
{\it subcircuit description}\\
{\tt .ends}
\end{verse}
%------------------------------------------------------------------------
\subsection{Purpose}

Logic element for mixed or logic mode simulation.
%------------------------------------------------------------------------
\subsection{Comments}

A sample 2 input nand gate might be: {\tt U102 (5 0 34 34 2 3) cmos nand}.
The input pins are connected to nodes 2 and 3.  The output is
at node 5.  Node 34 is the power supply.

The logic element behaves differently depending on the options {\tt
analog}, {\tt mixed}, or {\tt digital}.  You set one of these with the
{\tt options} command.  {\tt Analog} mode substitutes a subcircuit for
the gate for full analog simulation.  {\tt Digital} mode simulates the
gate as a digital device as in an event driven gate level logic
simulator.  {\tt Mixed} mode applies heuristics to decide whether to
use analog or digital for each gate.

In {\tt analog} mode the logic ({\tt U}) device is almost the same as
a subcircuit ({\tt X}).  The subcircuit is user defined for each gate
type used.  A {\tt .subckt} defines the analog equivalent of a logic
element.  The name of the subcircuit is made by concatenating the {\em
family}, {\em gatetype}, and the number of inputs.  For example, if
the {\em family} is {\tt cmos} and the {\em gatetype} is {\tt nand}
and it has two inputs, the name of the subcircuit is {\tt cmosnand2}.
So, the gate in the first paragraph becomes equivalent to: 
{\tt X (5 0 34 34 2 3) cmosnand2}.  You then need to define the
subcircuit using the standard {\tt .subckt} notation.  You can probe
the internal elements the same as an ordinary subcircuit.

The {\tt digital} mode uses simple boolean expressions to compute the
output, just like a gate level logic simulator.  In this case the
output is computed by L(5) = not(L(2) and L(3)) where L(2) is the
logic state at node 2.  The simulator exploits latency so it will only
compute the output if one of the inputs changes.  The output actually
changes after a delay, specified in the {\tt .model} statement.  There
are no conversions between digital and analog where gates connect
together.  There will be an automatic conversion from analog to
digital for any input that is driven by an analog device.  There will
be an automatic conversion from digital to analog for any output that
drives an analog device.  These conversions will only be done if they
are needed.  You can probe the analog value at any node.  The probe
will automatically request the conversion if it needs it.  There is no
internal subcircuit so it is an error to probe the internal elements.

The {\tt mixed} mode is a combination of analog and digital modes on a
gate by gate basis.  Some gates will be analog.  Some will be digital.
This will change as the simulation runs based on the quality of the
signals.  You need to specify a {\tt .subckt} as you do for the analog
mode, but the simulator may not use it.  You can usually not probe the
elements inside the subcircuit because they come and go.
%------------------------------------------------------------------------
\subsection{Element Parameters}

{\em Family} refers to the logic family {\tt .model} statement.

{\em Gatetype} is the type of logic gate:

\begin{description}

\item[{\tt AND}]

\item[{\tt NAND}]

\item[{\tt OR}]

\item[{\tt NOR}]

\item[{\tt XOR}]

\item[{\tt INV}]

\end{description}
%------------------------------------------------------------------------
\subsection{Model Parameters}

\subsubsection{Parameters used in digital mode}
\begin{description}

\item[{\tt DELAY} = {\it x}] Propagation delay.  (Seconds) (Default = 1e-9)
The propagation delay of a simple gate when simulated in logic mode.

\end{description}
%----------------------------------------
\subsubsection{Parameters used in conversion both ways}
\begin{description}

\item[{\tt VMAX} = {\it x}] Nominal logic 1.  (Volts) (Default = 5.) The
nominal value for a logic 1.

\item[{\tt VMIN} = {\it x}] Nominal logic 0.  (Volts) (Default = 0.) The
nominal value for a logic 0.

\item[{\tt UNKNOWN} = {\it x}] Nominal logic unknown.  (Volts) 
(Default = (vmax+vmin)/2) The output voltage for a logic unknown.  In
a real circuit, this voltage is unknown, but a simulator needs
something, so here it is.

\end{description}
%----------------------------------------
\subsubsection{Digital to Analog conversion}
\begin{description}

\item[{\tt RISE} = {\it x}] Rise time. (Seconds) (Default = delay / 2) The
nominal rise time of a logic signal.  This will be the rise time when
a logic signal is converted to analog.

\item[{\tt FALL} = {\it x}] Fall time. (Seconds) (Default = delay / 2) The
nominal fall time of a logic signal.  This will be the fall time when a
logic signal is converted to analog.

\item[{\tt RS} = {\it x}] Series resistance, strong. (Ohms) (Default =
100.)  The resistance in series with the output when a logic gate drives
analog circuitry.

\item[{\tt RW} = {\it x}] Series resistance, weak. (Ohms) (Default = 1e9)
The output resistance in a high impedance state.

\end{description}
%----------------------------------------
\subsubsection{Analog to Digital conversion}
\begin{description}

\item[{\tt THH} = {\it x}] Threshold high.  (Unitless) (Default = .75) The
threshold for the input to cross from transition to high expressed as a
fraction of the difference between high and low values.  (Low = 0.  High =
1.)

\item[{\tt THL} = {\it x}] Threshold low.  (Unitless) (Default = .25) The
threshold for the input to cross from transition to low expressed as a
fraction of the difference between high and low values.  (Low = 0.  High =
1.)

\end{description}
%----------------------------------------
\subsubsection{Mode decision parameters}
\begin{description}

\item[{\tt MR} = {\it x}] Margin rising.  (Unitless) (Default = 5) How much
worse than nominal the analog input rise time can be and still be accepted
as clean enough for logic simulation.

\item[{\tt MF} = {\it x}] Margin falling.  (Unitless) (Default = 5) How much
worse than nominal the analog input fall time can be and still be accepted
as clean enough for logic simulation.

\item[{\tt OVER} = {\it x}] Overshoot limit.  (Unitless) (Default = .1) How
much overshoot can a signal have and still be accepted as clean enough for
logic simulation, expressed as a fraction of the difference between high and
low values.  (Low = 0.  High = 1.)

\end{description}
%------------------------------------------------------------------------
\subsection{Probes}

Probing a logic device is equivalent to probing its output node.

\begin{description}

\item[{\tt V}]
Output voltage.

\item[{\tt LOGIC}]
A numeric interpretation of the logic value at the node.  The value is
displayed encoded in a number of the form $a.bc$ where $a$ is the
logic state: $0 =$ logic $0$, $1 =$ rising, $2 =$ falling, $3 =$ logic
$1$.  $b$ is an indication of the quality of the digital signal.  $0$
is a fully valid logic signal.  Nonzero indicates it does not meet the
criteria for logic simulation.  $c$ indicates how the node was
calculated: $0$ indicates logic simulation.  $1$ indicates analog
simulation of a logic device.  $2$ indicates analog simulation of
analog devices.

\item[{\tt LASTCHANGE}]
The most recent time at which the logic state changed.

\item[{\tt FINALTIME}]
The scheduled time a pending change will occur.

\end{description}

In this release, there are no probes available in AC analysis except for the
internal elements.  Internal elements in the analog model are available, but
they come and go so they may be unreliable.  More parameters will be added.

You can probe the logic value at any node.  See the {\tt print} command for
details.
%------------------------------------------------------------------------
%------------------------------------------------------------------------
