From 05983f3e65ecf0f21fa080f5beef50b23236aed3 Mon Sep 17 00:00:00 2001 From: jand Date: Tue, 4 Feb 2003 19:31:28 +0000 Subject: [PATCH] worked further --- doc/reference.tex | 160 +++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 144 insertions(+), 16 deletions(-) diff --git a/doc/reference.tex b/doc/reference.tex index dd6ebd78..86f86cb6 100644 --- a/doc/reference.tex +++ b/doc/reference.tex @@ -1,16 +1,17 @@ -\chapter{Reference} +\chapter{Reference manual} \myhdl\ is implemented as a Python package called \code{myhdl}. This chapter describes all objects that are expored by this package. \section{The \class{Simulation} class} -\begin{classdesc}{Simulation}{*args} +\begin{classdesc}{Simulation}{arg \optional{, arg \moreargs}} Class to construct a new simulation. Each argument can either be a \myhdl\ generator, or a nested sequence of such generators. (A nested sequence means that each item in the sequence can itself be a sequence.) See section~\ref{myhdl-generators} for the definition of -\myhdl\ generators. +\myhdl\ generators and their interaction with a \class{Simulation} +object. \end{classdesc} A \class{Simulation} instance has the following method: @@ -20,28 +21,90 @@ Run the simulation forever 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} has the following attributes: +A \class{Signal} object has the following attributes: \begin{memberdesc}[Signal]{val} Read-only attribute that represents the current value of the signal. - \end{memberdesc} \begin{memberdesc}[Signal]{next} -Read-write attribute. - +Read-write attribute that represents the next value of the signal. \end{memberdesc} -\end{classdesc} - -\section{\myhdl\ generators} +\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 is: + +\keyword{yield} \var{clause \optional{, clause ...}} + +After a simulator 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 when the \emph{first} trigger object +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. When referring to ``the generator'' we mean the generator +to which the \keyword{yield} statement belongs. + +\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 false to true. +\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}} +Joins a number of trigger objects together. The effect is that the +joined trigger object will only trigger when \emph{all} of its arguments +have triggered. +\end{funcdesc} + +In addition, some objects can directly function 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 itself be used as trigger objects. In this case, +the original generator is triggered when the spawned generator +completes. +\end{datadesc} -\section{Modeling convenience objects} +\section{Miscellaneous objects} -\begin{excclassdesc}{StopStimulation}{} +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} @@ -50,12 +113,77 @@ stop a simulation. Can be subclassed and raised in generator code. Return the current simulation time. \end{funcdesc} -\begin{funcdesc}{downrange}{high, \optional{low}} -Generates a downward range list. Like the standard \code{range} -function, but in the downward direction. +\begin{funcdesc}{downrange}{high, \optional{low=0}} +Generates a downward range list. Modeled after the standard +\code{range} function, but works in the downward direction. The +returned interval is half-open, with \var{high} not being +included. \var{low} is optional and defaults to zero. + +This function is especially useful with the \class{intbv} class, that +also works with downward indexing. \end{funcdesc} -\section{The \class{intbv} class} +\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 \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 +and immutable type.) + +An \class{intbv} object supports all comparison, numberic, bitwise, +and logical 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}]} + {\var{i}'th item 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 to \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 + 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)] slicing + +\item[(3)] positive return + +\item[(4)] value check + +\end{description} + + +