index

doc/manual/background.tex

@@ -103,8 +103,8 @@ some form of threading.
 
 The use of generators to model concurrency is the first key concept in
 \myhdl{}. The second key concept is a related one: in \myhdl{}, the
-yielded values are used to define the condition upon which the
-generator should resume. In other words, \keyword{yield}
+yielded values are used to specify the conditions on which the
+generator should wait before resuming. In other words, \keyword{yield}
 statements work as generalized 
     \index{sensitivity list}%
 sensitivity lists. 

doc/manual/cosimulation.tex

@@ -23,7 +23,7 @@ side is designed to be independent of a particular
 simulator, On the other hand, for each HDL simulator a specific
 PLI module will have to be written in C. Currently,
 the \myhdl\ release contains a PLI module to interface
-to the Icarus Verilog simulator. This interface will
+with the Icarus Verilog simulator. This interface will
 be used in the examples.
 
 \section{The HDL side \label{cosim-hdl}}

doc/manual/informal.tex

@@ -47,8 +47,10 @@ a classic Python function) because it contains a \keyword{yield}
 statement (instead of \keyword{return} statement). In \myhdl{}, a
 \keyword{yield} statement has a similar purpose as a \keyword{wait}
 statement in VHDL: the statement suspends execution of the function,
-while its clauses specify when the function should resume. In this case,
-there is a \code{delay} clause, that specifies the required delay.
+and its clauses specify the conditions on which the generator should
+wait before resuming. In this case, it should
+    \index{wait!for a delay}%
+wait for a delay.
 
 To make sure that the generator runs ``forever'', we wrap its behavior
 in a \code{while 1} loop. This is a standard Python idiom, and it is
@@ -114,10 +116,11 @@ def sayHello():
         print "%s Hello World!" % now()
 \end{verbatim}
 
-Waiting for a clock edge is achieved with a second form of the
+Waiting for the clock edge is achieved with a second form of the
 \keyword{yield} statement: \samp{yield posedge(\var{signal})}. 
-A \class{Simulation} object will suspend the generator as that point,
-and resume it when there is a rising edge on the signal.
+At that point, the generator will
+    \index{wait!for a rising edge}%
+wait for a rising edge on the signal.
 
 The \class{Simulation} is now constructed with 2 generator arguments:
 
@@ -175,7 +178,7 @@ We can create any number of generators by calling generator functions
 with the appropriate parameters. This is very similar to the concept
 of instantiation in hardware description languages and we will use
 the same terminology in \myhdl{}. A \myhdl\ \dfn{instance} is
-    \index{instance!defined}
+    \index{instance!defined}%
 recursively defined as being either a sequence of instances, or a
 generator.  Hierarchy can be modeled by defining the instances in a
 higher-level function, and returning them. 
@@ -219,7 +222,34 @@ StopSimulation: Simulated for duration 50
 \end{verbatim}
 
 
-\section{Bit-oriented operations \label{intro-bit}}
+\begin{notice}[warning]
+Some commonly used terminology has different meanings
+in Python and hardware design. Rather than artificially
+changing terminology, I think it's best to keep it
+and explicitly describing the differences.
+
+A \dfn{module} in Python refers to all source code
+in a particular file. A module can be reused by
+other modules by importing. In hardware design,
+\index{module!in Python versus hardware design}%
+a module is  a reusable block of hardware with
+a well defined interface. It can be reused in 
+another module by \dfn{instantiating} it.
+
+An \dfn{instance} in Python (and other object-oriented
+languages) refers to the object created by a
+\index{instance!in Python versus hardware design}%
+class constructor. In hardware design, an instance
+is a particular incarnation of a hardware module.
+
+Normally, the meaning should be clear from
+the context. Occasionally, I may qualify terms 
+with the words 'hardware' or '\myhdl{}' to 
+avoid ambiguity.
+\end{notice}
+
+
+\section{Bit oriented operations \label{intro-bit}}
 
 Hardware design involves dealing with bits and bit-oriented
 operations. The standard Python type \class{int} has most of the
@@ -234,7 +264,9 @@ operations. In addition, it is a mutable type that provides indexing
 and slicing operations, and some additional bit-oriented support such
 as concatenation.
 
-\subsection{Indexing operations \label{intro-indexing}}
+\subsection{Bit indexing operations \label{intro-indexing}}
+\index{bit indexing}
+
 As an example, we will consider the design of a Gray encoder. The
 following code is a Gray encoder modeled in \myhdl{}:
 
@@ -258,7 +290,8 @@ at the start of the function is a \dfn{doc string}. This is standard
 Python practice for structured documentation of code. Moreover, we
 use a third form of the \keyword{yield} statement:
 \samp{yield \var{signal}}. This specifies that the generator should
-resume whenever \var{signal} changes value. This is typically used to
+    \index{wait!for a signal value change}%
+wait for a signal value change. This is typically used to
 describe 
     \index{combinatorial logic}%
 combinatorial logic.
@@ -312,7 +345,8 @@ B: 111 | G: 100
 StopSimulation: No more events
 \end{verbatim}
 
-\subsection{Slicing operations \label{intro-slicing}}
+\subsection{Bit slicing operations \label{intro-slicing}}
+\index{bit slicing}
 
 For a change, we will use a plain function as an example to illustrate
 slicing.  The following function calculates the HEC byte of an ATM
@@ -425,11 +459,12 @@ We use the bus functional procedure call as a clause in a
 \code{yield} statement. This introduces a fourth form of the
 \code{yield} statement: using a generator as a clause. Although this is
 a more dynamic usage than in the previous cases, the meaning is
-actually very similar. When the calling generator \code{stimulus()}
-encounters the \code{yield} statement, it suspends execution, and the
-clause specifies when it should resume. In this case, the generator
-\code{rs232_tx(tx, txData)} is \dfn{forked}, and the caller resumes
-when the forked generator returns.
+actually very similar: at that point,
+the original generator should 
+    \index{wait!for the completion of a generator}% 
+wait for the completion of a generator. 
+In this case, the original generator resumes when the
+\code{rs232_tx(tx, txData)} generator returns.
 
 When simulating this, we get:
 

doc/manual/modeling.tex

@@ -1,6 +1,7 @@
 \chapter{Modeling techniques \label{model}}
 
 \section{Structural modeling \label{model-structure}}
+\index{modeling!structural}
 
 Hardware descriptions need to support the concepts of module
 instantiation and hierarchy.  In \myhdl{}, an instance is recursively
@@ -25,6 +26,7 @@ for modeling structure. This makes it straightforward
 to model more complex cases.
 
 \subsection{Conditional instantiation \label{model-conf}}
+\index{conditional instantiation}
 
 To model conditional instantiation, we can
 select the returned instance under parameter control.
@@ -50,6 +52,7 @@ def top(..., speed=SLOW):
 
 
 \subsection{Arrays of instances \label{model-instarray}}
+\index{arrays of instances}
 
 Python lists are easy to create. We can use them
 to model arrays of instances. 
@@ -118,11 +121,13 @@ that comply with the definition of an instance are assembled in
 a list, and that list is returned.
 
 \section{RTL modeling \label{model-rtl}}
+\index{modeling!RTL style}
+
 The present section describes how \myhdl\ supports RTL style modeling
 as is typically used for synthesizable models in Verilog or VHDL. 
 
-\subsection{Combinatorial logic \label{model-comb}}
-\index{combinatorial logic|(}
+\subsection{Combinatorial logic modeling\label{model-comb}}
+\index{modeling!combinatorial logic|(}
 
 \subsubsection{Template \label{model-comb-templ}}
  
@@ -240,11 +245,11 @@ z a b sel
 3 3 5 1
 StopSimulation: No more events
 \end{verbatim}
-\index{combinatorial logic|)}
+\index{modeling!combinatorial logic|)}
 
 
-\subsection{Sequential logic \label{model-seq}}
-\index{sequential logic|(}
+\subsection{Sequential logic modeling\label{model-seq}}
+\index{modeling!sequential logic|(}
 
 \subsubsection{Template \label{model-seq-templ}}
 Sequential RTL models are sensitive to a clock edge. In addition, they
@@ -347,6 +352,7 @@ StopSimulation
 
 
 \subsection{Finite State Machine modeling \label{model-fsm}}
+\index{modeling!Finite State Machine}
 
 Finite State Machine (FSM) modeling is very common in RTL
 design and therefore deserves special attention.
@@ -457,7 +463,9 @@ def FramerCtrl(SOF, state, syncFlag, clk, reset_n):
 \end{verbatim}
 
 At this point, we will use the example to demonstrate
-the \myhdl\ support for waveform viewing.
+the \myhdl\ support for 
+\index{waveform viewing}%
+waveform viewing.
 During simulation, signal
 changes can be written to a VCD output file.  The VCD file can then be
 loaded and viewed in a waveform viewer tool such as \program{gtkwave}.
@@ -552,6 +560,7 @@ only.
 
 
 \section{High level modeling \label{model-hl}}
+\index{modeling!high level}
 
 \begin{quote}
 \em 
@@ -564,6 +573,7 @@ prove useful will be added.
 \end{quote}
 
 \subsection{Modeling memories with built-in types \label{model-mem}}
+\index{modeling!memories}
 
 Python has powerful built-in data types that can be useful to model
 hardware memories. This can be merely a matter of putting an interface
@@ -747,7 +757,8 @@ overflow error is detected by a regular check on the length of the
 list.
 
 
-\subsection{Object-oriented modeling \label{model-obj}}
+\subsection{Object oriented modeling \label{model-obj}}
+\index{modeling!object oriented}
 
 The models in the previous sections used high-level built-in data
 types internally. However, they had a conventional RTL-style

doc/manual/unittest.tex

@@ -310,7 +310,7 @@ prefixing all codewords of Ln with '1', and reversing their
 order. Ln+1 is the concatenation of Ln0 and Ln1.
 \end{enumerate}
 
-Python is well-known  for its elegant algorithmic
+Python is well-known for its elegant algorithmic
 descriptions, and this is a good example. We can write the algorithm
 in Python as follows: