adapted

doc/manual/background.tex

@@ -112,7 +112,7 @@ documentation, e.g. at \url{http://www.python.org/doc/2.2.2/whatsnew}.
 
 \begin{notice}[warning]
 As mentioned earlier, generators were introduced in Python 2.2. In
-that version, they are introduced as a ``future'' feature that has to
+that version, they were introduced as a ``future'' feature that has to
 be enabled explicitly. In Python 2.3, which is the latest stable
 Python version at the time of this writing, generators are enabled by
 default.

doc/manual/modeling.tex

@@ -1,10 +1,16 @@
 \chapter{Modeling techniques \label{model}}
 
+\section{Structural modeling \label{model-structure}}
+
+\subsection{Configurations \label{model-conf}}
+
+\subsection{Arrays of instances \label{model-instarray}}
+
+\subsection{Inferring the list of all instances \label{model-infer-instlist}}
+
 \section{RTL modeling \label{model-rtl}}
 The present section describes how \myhdl\ supports RTL style modeling
-as is typically used for synthesizable models in Verilog or VHDL. This
-section is included mainly for illustrative purposes, as this modeling
-style is well known and understood.
+as is typically used for synthesizable models in Verilog or VHDL. 
 
 \subsection{Combinatorial logic \label{model-comb}}
 
@@ -16,14 +22,33 @@ follows:
 \begin{verbatim}
 def combinatorialLogic(<arguments>)
     while 1:
-        yield <input signal arguments>
+        yield <input signals>
         <functional code>
 \end{verbatim}
 
 The overall code is wrapped in a \code{while 1} statement to keep the
 generator alive. All input signals are clauses in the \code{yield}
 statement, so that the generator resumes whenever one of the inputs
-changes. 
+changes.
+
+Note that the input signals are listed explicitly in the
+template. Alternatively, \myhdl\ provides the \function{always_comb()}
+function to infer the input signals automatically. The name refers to
+a construct with similar semantics in SystemVerilog.  The argument of
+\function{always_comb()} is a local function that specifies
+what happens when one of the input signals
+changes. It returns a generator that is
+sensitive to all inputs, and that will run the function argument
+whenever an input changes. Using \function{always_comb}, the template
+can be rewritten as follows:
+
+\begin{verbatim}
+def combinatorialLogic(<arguments>)
+    def logicFunction():
+        <functional code>
+    return always_comb(logicFunction)
+\end{verbatim}
+
 
 \subsubsection{Example \label{model-comb-ex}}
 
@@ -193,15 +218,12 @@ StopSimulation
 \section{High level modeling \label{model-hl}}
 
 \begin{quote}
-\em
+\em 
 This section on high level modeling should become an exciting part of
 the manual, but it doesn't contain a lot of material just yet. One
 reason is that I concentrated on the groundwork first. Moreover,
 though I expect Python to offer some very powerful capabilities in
-this domain, I'm just starting to experiment and learn myself. For
-example, note that so far we haven't used classes (nor meta-classes
-:-)) yet, even though Python has a very powerful object-oriented
-model.
+this domain, I'm just starting to experiment and learn myself. 
 \end{quote}
 
 \subsection{Modeling memories with built-in types \label{model-mem}}
@@ -388,7 +410,3 @@ overflow error is detected by a regular check on the length of the
 list.
 
 
-\begin{quote}
-\em
-A lot to be added ...
-\end{quote}

doc/manual/reference.tex

@@ -8,15 +8,15 @@ chapter describes the objects that are exported by this package.
 \declaremodule{}{myhdl}
 
 \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{ref-gen} for the
-definition of \myhdl\ generators and their interaction with a
-\class{Simulation} object.
+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.
 
-As a special case, exactly one of the arguments may be
-a \class{Cosimulation} object (see Section~\ref{ref-cosim}).
 \end{classdesc}
 
 A \class{Simulation} object has the following method:
@@ -38,16 +38,15 @@ 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}}
+\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 a nested sequence of
-generators that represents an instance
-hierarchy. \function{traceSignals()} call \var{func} under its control
+\var{func} is a function that returns an instance.
+\function{traceSignals()} call \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
+\code{func(*args, **kwargs)}. It should be assigned
 to a top level instance name. For example:
 \begin{verbatim}
 topname = traceSignals(func, ...)
@@ -84,7 +83,7 @@ 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}
+addition, when a Signal object is assigned to the \code{next}
 attribute of another Signal object, its current value is assigned
 instead.
 \end{memberdesc}
@@ -158,7 +157,8 @@ generator is triggered.
 
 \item[\class{GeneratorType}]
 \myhdl\ generators can be used as clauses in \code{yield}
-statements. Such a generator is forked, while the original generator
+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}
@@ -195,7 +195,7 @@ 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.
+useful in hardware design.
 \end{funcdesc}
 
 \begin{funcdesc}{concat}{base \optional{, arg \moreargs}}
@@ -206,7 +206,7 @@ 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, \class{intbv}, \class{int} and \class{long} objects
+objects, unsized \class{intbv}, \class{int} and \class{long} objects
 are supported, as well as signals of such objects.
 \end{funcdesc}
 
@@ -234,15 +234,14 @@ the typename, for example: \code{t_EnumType.ATTR_NAME_1}
 \end{funcdesc}
 
 \begin{funcdesc}{instances}{}
-Looks up all instances in the local namespace and returns them as a
-list.  In \myhdl{}, an instance is defined as a nested sequence of
-generators.
+Looks up all \myhdl\ instances in the local namespace and returns them
+in a list.
 
 \end{funcdesc}
 \begin{funcdesc}{processes}{}
 Looks up all processes in the local namespace, calls each of them,
-returns the resulting generators as a list.  In \myhdl{}, a process is
-defined as a locally defined generator function,
+returns the resulting generators in a list.  In \myhdl{}, a process is
+defined as a local generator function with no parameters.
 \end{funcdesc}
 
 \section{The \class{intbv} class \label{ref-intbv}}
@@ -331,13 +330,13 @@ operations:
           to \code{0}. When the high index \var{i} is omitted, it
           means ``all'' higher order bits.
 
-\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. 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[(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.