From 55237e27c19b6d0db5912a7c3c0f9d3f0415c423 Mon Sep 17 00:00:00 2001 From: jand Date: Wed, 27 Aug 2003 14:17:06 +0000 Subject: [PATCH] index --- doc/manual/background.tex | 4 +-- doc/manual/cosimulation.tex | 2 +- doc/manual/informal.tex | 65 ++++++++++++++++++++++++++++--------- doc/manual/modeling.tex | 25 ++++++++++---- doc/manual/unittest.tex | 2 +- 5 files changed, 72 insertions(+), 26 deletions(-) diff --git a/doc/manual/background.tex b/doc/manual/background.tex index 6f057c5c..78bbac09 100644 --- a/doc/manual/background.tex +++ b/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. diff --git a/doc/manual/cosimulation.tex b/doc/manual/cosimulation.tex index a1c106d9..feaa2e58 100644 --- a/doc/manual/cosimulation.tex +++ b/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}} diff --git a/doc/manual/informal.tex b/doc/manual/informal.tex index 591ccff9..211c0b06 100644 --- a/doc/manual/informal.tex +++ b/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: diff --git a/doc/manual/modeling.tex b/doc/manual/modeling.tex index 559e043a..4e515575 100644 --- a/doc/manual/modeling.tex +++ b/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 diff --git a/doc/manual/unittest.tex b/doc/manual/unittest.tex index 64268b5b..19ff89cf 100644 --- a/doc/manual/unittest.tex +++ b/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: