myhdl/doc/manual/reference.tex

\chapter{Reference \label{ref}}


\myhdl\ is implemented as a Python package called \code{myhdl}. This
chapter describes the objects that are exported by this package.

\section{The \class{Simulation} class \label{ref-sim}}
\declaremodule{}{myhdl}

\begin{classdesc}{Simulation}{arg \optional{, arg \moreargs}}
Class to construct a new simulation. Each argument should be a
\myhdl\ instance. In \myhdl{}, an instance is recursively defined
as being either a sequence of instances, or a \myhdl\ generator, or a
Cosimulation object. See section~\ref{ref-gen} for the definition of
\myhdl\ generators and their interaction with a
\class{Simulation} object.  See Section~\ref{ref-cosim}
for the \class{Cosimulation} object.  At most one \class{Cosimulation}
object can be passed to a \class{Simulation} constructor.

\end{classdesc}

A \class{Simulation} object has the following method:

\begin{methoddesc}[Simulation]{run}{\optional{duration}}
Run the simulation forever (by default) or for a specified duration.
\end{methoddesc}


\section{Simulation support\label{ref-simsupport}}
\declaremodule{}{myhdl}

\begin{funcdesc}{now}{}
Returns the current simulation time.
\end{funcdesc}

\begin{excclassdesc}{StopSimulation}{}
Base exception that is caught by the \code{Simulation.run()} method to
stop a simulation.
\end{excclassdesc}

\begin{funcdesc}{traceSignals}{func \optional{, *args} \optional{, **kwargs}}
Enables signal tracing to a VCD file for waveform viewing.
\var{func} is a function that returns an instance.
\function{traceSignals()} calls \var{func} under its control
and passes \var{*args} and \var{**kwargs} to the call. In this way, it
finds the hierarchy and the signals to be traced.

The return value is the same as would be returned by the call
\code{func(*args, **kwargs)}. It should be assigned
to a top level instance name. For example:
\begin{verbatim}
topname = traceSignals(func, ...)
\end{verbatim}
The resulting VCD file will be named after the top level instance
name. In the example, it would be called \file{topname.vcd}.  If the
VCD file exists already, it will be moved to a backup file by
attaching a timestamp to it, before creating the new file.
\end{funcdesc}


\section{The \class{Signal} class \label{ref-sig}}
\declaremodule{}{myhdl}

\begin{classdesc}{Signal}{\optional{val=None} \optional{, delay=0}}
This class is used to construct a new signal and to initialize its
value to \var{val}. Optionally, a delay can be specified.
\end{classdesc}

A \class{Signal} object has the following attributes:

\begin{memberdesc}[Signal]{next}
Read-write attribute that represents the next value of the signal.
\end{memberdesc}

\begin{memberdesc}[Signal]{val}
Read-only attribute that represents the current value of the signal.

This attribute is always available to access the current value;
however in many practical case it will not be needed. Whenever there
is no ambiguity, the Signal object's current value is used
implicitly. In particular, all Python's standard numeric, bit-wise,
logical and comparison operators are implemented on a Signal object by
delegating to its current value. The exception is augmented
assignment. These operators are not implemented as they would break
the rule that the current value should be a read-only attribute. In
addition, when a Signal object is assigned to the \code{next}
attribute of another Signal object, its current value is assigned
instead.
\end{memberdesc}

\begin{memberdesc}[Signal]{min}
Read-only attribute that is the minimum value (inclusive) of a
numeric signal, or \var{None} for no minimum.
\end{memberdesc}
\begin{memberdesc}[Signal]{max}
Read-only attribute that is the maximum value
(exclusive) of a numeric signal, or \var{None} for no 
maximum.
\end{memberdesc}

\section{\myhdl\ generators and trigger objects \label{ref-gen}}
\declaremodule{}{myhdl}

\myhdl\ generators are standard Python generators with specialized
\keyword{yield} statements. In hardware description languages, the equivalent
statements are called 
    \index{sensitivity list}%
\emph{sensitivity lists}. The general format
of \keyword{yield} statements in in \myhdl\ generators is:

\hspace{\leftmargin}\keyword{yield} \var{clause \optional{, clause ...}}

When a generator executes a \keyword{yield} statement, its
execution is suspended at that point. At the same time, each
\var{clause} is a \emph{trigger object} which defines the condition
upon which the generator should be resumed. However, per invocation of a
\keyword{yield} statement, the generator is resumed exactly once,
regardless of the number of clauses. This happens as soon as one
of the objects triggers; subsequent triggers are
neglected. (However, as a result of the resumption, it is possible
that the same \keyword{yield} statement is invoked again, and that a
subsequent trigger still triggers the generator.)

In this section, the trigger objects and their functionality will be
described. 

\begin{funcdesc}{posedge}{signal}
Return a trigger object that specifies that the generator should
resume on a rising edge on the signal. A rising edge means a change
from false to true.
\end{funcdesc}

\begin{funcdesc}{negedge}{signal}
Return a trigger object that specifies that the generator should
resume on a falling edge on the signal. A falling edge means a change
from true to false.
\end{funcdesc}

\begin{funcdesc}{delay}{t}
Return a trigger object that specifies that the generator should
resume after a delay \var{t}.
\end{funcdesc}

\begin{funcdesc}{join}{arg \optional{, arg \moreargs}}
Join a number of trigger objects together and return a joined
trigger object.  The effect is that the joined trigger object will
trigger when \emph{all} of its arguments have triggered.
\end{funcdesc}

In addition, some objects can directly be used as trigger
objects. These are the objects of the following types:

\begin{description}
\item[\class{Signal}]
For the full description of the \class{Signal} class, see
section~\ref{ref-sig}.
A signal is a trigger object. Whenever a signal changes value, the
generator is triggered.

\item[\class{GeneratorType}]
\myhdl\ generators can be used as clauses in \code{yield}
statements. Such a generator is forked, and starts operating
while the original generator
waits for it to complete. The original generator resumes when the
forked generator returns.
\end{description}

In addition, as a special case, the Python \code{None} object can be
present in  a \code{yield} statement:
\begin{description}

\item[\code{None}]
This is the do-nothing trigger object. The generator immediately
resumes, as if no \code{yield} statement were present. This can be
useful if the \code{yield} statement also has generator clauses: those
generators are forked, while the original generator resumes
immediately.
\end{description}



\section{Modeling support\label{ref-misc}}
\declaremodule{}{myhdl}

\begin{funcdesc}{always_comb}{func}
Returns a generator that is sensitive to all signals that
are used as inputs in function \function{func()}. The generator
will run \function{func()} whenever one of the inputs changes.
\function{func()} should be a locally defined function without
parameters.
\end{funcdesc}

\begin{funcdesc}{bin}{num \optional{, width}}
Returns a bit string representation. If the optional \var{width}
is provided, and if it is larger than the width of the default
representation, the bit string is padded with the sign bit.

This function complements the standard Python conversion functions
\code{hex} and \code{oct}. A binary string representation is often
useful in hardware design.
\end{funcdesc}

\begin{funcdesc}{concat}{base \optional{, arg \moreargs}}
Returns an \class{intbv} object formed by concatenating the arguments.

The following argument types are supported: \class{intbv} objects with
a defined bit width, \class{bool} objects, signals of the previous
objects, and bit strings. All these objects have a defined bit
width. The first argument \var{base} is special as it doesn't need to
have a defined bit width. In addition to the previously mentioned
objects, unsized \class{intbv}, \class{int} and \class{long} objects
are supported, as well as signals of such objects.
\end{funcdesc}

\begin{funcdesc}{downrange}{high \optional{, low=0}}
Generates a downward range list of integers.

This function is modeled after the standard \code{range} function, but
works in the downward direction. The returned interval is half-open,
with the \var{high} index not included. \var{low} is optional and
defaults to zero.  This function is especially useful in conjunction
with the \class{intbv} class, that also works with downward indexing.
\end{funcdesc}

\begin{funcdesc}{enum}{arg \optional{, arg \moreargs}}
Returns an enumeration type.

The arguments should be string literals that represent the desired
names of the enumeration type attributes.  The returned type should be
assigned to a type name.  For example:
\begin{verbatim}
t_EnumType = enum('ATTR_NAME_1', 'ATTR_NAME_2', ...)
\end{verbatim}
The enumeration type identifiers are available as attributes of
the type name, for example: \code{t_EnumType.ATTR_NAME_1}
\end{funcdesc}

\begin{funcdesc}{instances}{}
Looks up all \myhdl\ instances in the local name space and returns them
in a list.

\end{funcdesc}
\begin{funcdesc}{processes}{}
Looks up all generator functions without parameters in the local name
space, calls each of them, and returns the resulting generators in a list.
\end{funcdesc}

\section{The \class{intbv} class \label{ref-intbv}}
\declaremodule{}{myhdl}

\begin{classdesc}{intbv}{\optional{val=0} \optional{, min=None} 
\optional{, max=None}}
This class represents \class{int}-like objects with some additional
features that make it suitable for hardware design. The \var{val}
argument can be an \class{int}, a \class{long}, an \class{intbv} or a
bit string (a string with only '0's or '1's). For a bit string
argument, the value is calculated as in \code{int(\var{bitstring},
2)}.  The optional \var{min} and \var{max} arguments can be used to
specify the minimum and maximum value of the \class{intbv} object. As
in standard Python practice for ranges, the minimum value is inclusive
and the maximum value is exclusive.
\end{classdesc}

The minimum and maximum values of an \class{intbv} object
are available as attributes:

\begin{memberdesc}[intbv]{min}
Read-only attribute that is the minimum value (inclusive) of an
\class{intbv}, or \var{None} for no minimum.
\end{memberdesc}
\begin{memberdesc}[intbv]{max}
Read-only attribute that is the maximum value
(exclusive) of an \class{intbv}, or \var{None} for no 
maximum.
\end{memberdesc}

Unlike \class{int} objects, \class{intbv} objects are mutable; this is
also the reason for their existence. Mutability is needed to support
assignment to indexes and slices, as is common in hardware design. For
the same reason, \class{intbv} is not a subclass from \class{int},
even though \class{int} provides most of the desired
functionality. (It is not possible to derive a mutable subtype from
an immutable base type.)

An \class{intbv} object supports the same comparison, numeric,
bitwise, logical, and conversion operations as \class{int} objects. See
\url{http://www.python.org/doc/current/lib/typesnumeric.html} for more
information on such operations. In all binary operations,
\class{intbv} objects can work together with \class{int} objects.
For mixed-type numeric operations, the result type is an \class{int}
or a \class{long}. For mixed-type bitwise operations, the result
type is an \class{intbv}.

In addition, \class{intbv} objects support indexing and slicing
operations:

\begin{tableiii}{clc}{code}{Operation}{Result}{Notes}
  \lineiii{\var{bv}[\var{i}]}
	  {item \var{i} of \var{bv}}
	  {(1)}
  \lineiii{\var{bv}[\var{i}] = \var{x}}  
	  {item \var{i} of \var{bv} is replaced by \var{x}} 
          {(1)}
  \lineiii{\var{bv}[\var{i}:\var{j}]} 
          {slice of \var{bv} from \var{i} downto \var{j}} 
          {(2)(3)}
  \lineiii{\var{bv}[\var{i}:\var{j}] = \var{t}} 
  	  {slice of \var{bv} from \var{i} downto \var{j} is replaced
          by \var{t}} 
          {(2)(4)}
\end{tableiii}

\begin{description}
\item[(1)] Indexing follows the most common hardware design
	  conventions: the lsb bit is the rightmost bit, and it has
	  index 0. This has the following desirable property: if the
	  \class{intbv} value is decomposed as a sum of powers of 2,
	  the bit with index \var{i} corresponds to the term
	  \code{2**i}.

\item[(2)] In contrast to standard Python sequencing conventions,
	  slicing range are downward. This is a consequence of the
	  indexing convention, combined with the common convention
	  that the most significant digits of a number are the
	  leftmost ones. The Python convention of half-open ranges is
	  followed: the bit with the highest index is not
	  included. However, it is the \emph{leftmost} bit in this
	  case. As in standard Python, this takes care of one-off
	  issues in many practical cases: in particular,
	  \code{bv[\var{i}:]} returns \var{i} bits;
	  \code{bv[\var{i}:\var{j}]} has \code{\var{i}-\var{j}}
	  bits. When the low index \var{j} is omitted, it defaults
          to \code{0}. When the high index \var{i} is omitted, it
          means ``all'' higher order bits.

\item[(3)] The object returned from a slicing access operation is always a
	  positive \class{intbv}; higher order bits are implicitly
	  assumed to be zero. The bit width is implicitly stored in
	  the return object, so that it can be used in concatenations
	  and as an iterator. In addition, for a bit width w, the
	  \var{min} and \var{max} attributes are implicitly set to
	  \code{0} and \code{2**w}, respectively.  

\item[(4)] In setting a slice, it is checked whether the slice is wide
	  enough to accept all significant bits of the value.
\end{description}

In addition, an \class{intbv} object supports the iterator protocol. This
makes it possible to iterate over all its bits, from the high index to
index 0. This is only possible for \class{intbv} objects with a
defined bit width.


\section{Co-simulation\label{ref-cosim}}
\declaremodule{}{myhdl}

\subsection{\myhdl\ \label{ref-cosim-myhdl}}

\begin{classdesc}{Cosimulation}{exe, **kwargs}
Class to construct a new Cosimulation object. 

The \var{exe} argument is a command string to
execute an HDL simulation. The \var{kwargs} keyword
arguments provide a named association between signals
(regs \& nets) in the HDL simulator and signals in the
\myhdl\ simulator. Each keyword should be a name listed
in a \code{\$to_myhdl} or \code{\$from_myhdl} call in
the HDL code. Each argument should be a \class{Signal}
declared in the \myhdl\ code.

\end{classdesc}

\subsection{Verilog \label{ref-cosim-verilog}}

\begin{funcdesc}{\$to_myhdl}{arg, \optional{, arg \moreargs}}
Task that defines which signals (regs \& nets) should be
read by the \myhdl\ simulator.
This task should be called at the start of the simulation.
\end{funcdesc}

\begin{funcdesc}{\$from_myhdl}{arg, \optional{, arg \moreargs}}
Task that defines which signals should be
driven by the \myhdl\ simulator. In Verilog, only regs
can be specified.
This task should be called at the start of the simulation.
\end{funcdesc}


\subsection{VHDL \label{ref-cosim-vhdl}}

Not implemented yet.

\section{Conversion to Verilog\label{ref-conv}}
\declaremodule{}{myhdl}

\begin{funcdesc}{toVerilog}{func \optional{, *args} \optional{, **kwargs}}
Converts a \myhdl\ design instance to equivalent Verilog
code, and also generates a test bench to verify it.
\var{func} is a function that returns an instance.
\function{toVerilog()} calls \var{func} under its control
and passes \var{*args} and \var{**kwargs} to the call.
\end{funcdesc}

For more information abuut the restrictions on convertible
\myhdl\ code, see section~\ref{conv-subset} in
Chapter~\ref{conv}.