\chapter{Reference} \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} \begin{classdesc}{Simulation}{arg \optional{, arg \moreargs}} Class to construct a new simulation. Each argument is either be a \myhdl\ generator, or a nested sequence of such generators. (A nested sequence is defined as a sequence in which each item may itself be a nested sequence.) See section~\ref{myhdl-generators} for the definition of \myhdl\ generators and their interaction with a \class{Simulation} object. As a special case, exactly one of the ``generators'' may be a \class{Cosimulation} object (see Section~\ref{cosimulation}). \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{The \class{Signal} class} \label{signal} \begin{classdesc}{Signal}{val \optional{, delay}} 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 directly assigned to the \code{next} attribute of another Signal object, its current value is assigned instead. \end{memberdesc} \section{\myhdl\ generators and trigger objects} \label{myhdl-generators} \myhdl\ generators are standard Python generators with specialized \keyword{yield} statements. In hardware description languages, the equivalent statements are called \emph{sensitivity lists}. The general format of \keyword{yield} statements in in \myhdl\ generators is: \hspace{\leftmargin}\keyword{yield} \var{clause \optional{, clause ...}} After a simulation object executes a \keyword{yield} statement, it suspends execution of the generator. 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{datadesc}{Signal} For the full description of the \class{Signal} class, see section~\ref{signal}. A signal is a trigger object. Whenever a signal changes value, the generator is triggered. \end{datadesc} \begin{datadesc}{GeneratorType} \myhdl\ generators can be used as clauses in \code{yield} statements. Such a generator is forked, while the original generator waits for it to complete. The original generator resumes when the forked generator returns. \end{datadesc} In addition, as a special case, the Python \code{None} object can be present in a \code{yield} statement: \begin{datadesc}{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{datadesc} \section{Miscellaneous objects} The following objects can be convenient in \myhdl\ modeling. \begin{excclassdesc}{StopSimulation}{} Base exception that is caught by the \code{Simulation.run} method to stop a simulation. Can be subclassed and raised in generator code. \end{excclassdesc} \begin{funcdesc}{now}{} Return the current simulation time. \end{funcdesc} \begin{funcdesc}{downrange}{high \optional{, low=0}} Generate 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}{bin}{num \optional{, width}} Return a representation as a bit string. 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 needed in hardware design. \end{funcdesc} \section{The \class{intbv} class} \begin{classdesc}{intbv}{arg} This class represents \class{int}-like objects with some additional features that make it suitable for hardware design. The constructor 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)}. \end{classdesc} 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; in those cases the return type is an \class{intbv} object. 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. As \class{intbv} objects have no explicitly defined bit width, the high index \var{j} has no default value and cannot be omitted, while the low index \var{j} defaults to \code{0}. \item[(3)] The value returned from a slicing operation is always positive; higher order bits are implicitly assumed to be zero. The bit width is implicitly stored in the returned bit width, so that the returned object can be used in concatenations and as an iterator. \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, \class{intbv} objects support a concatenation method: \begin{methoddesc}[intbv]{concat}{\optional{arg \moreargs}} Concatenate the arguments to an \class{intbv} object. Naturally, the concatenation arguments need to have a defined bit width. Therefore, if they are \class{intbv} objects, they have to be the return values of a slicing operation. Alternatively, they may be bit strings. In contrast to all other arguments, the implicit \var{self} argument doesn't need to have a defined bit with. This is due to the fact that concatenation occurs at the lsb (rightmost) side. It may be clearer to call this method as an unbound method with an explicit first \class{intbv} argument. \end{methoddesc} 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{Cosimulation support} \subsection{\myhdl\ } \label{cosimulation} \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} \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} Not implemented yet.