proofreading

doc/manual/MyHDL.tex

@@ -21,47 +21,63 @@
 
 \noindent
 
-\myhdl{} is a Python package for using Python as a hardware description
-and verification language. Languages such Verilog and VHDL are
-compiled languages. Python with \myhdl{} can be viewed as a "scripting
-language" counterpart of such languages. However, Python is more
-accurately described as a very high level language (VHLL). \myhdl{} users
-have access to the amazing power and elegance of Python.
+The goal of the \myhdl{} project is to empower hardware designers with
+the elegance and simplicity of the Python language.
 
-The key idea behind \myhdl{} is to use Python generators for modeling
-hardware concurrency. A generator is a resumable function with
-internal state. In \myhdl{}, a hardware module is modeled as a function
-that returns generators. With this approach, \myhdl{} directly supports
-features such as named port association, arrays of instances, and
-conditional instantiation. 
+\myhdl{} is a free, open-source (LGPL) package for using Python as a
+hardware description and verification language. Python is a very high
+level language, and hardware designers can use its full power to model
+and simulate their designs. Moreover, \myhdl{} can convert a design to
+Verilog. In combination with an external synthesis tool, it provides a
+complete path from Python to a silicon implementation.
 
-\myhdl{} supports the classic hardware description concepts.  It
-provides a signal class similar to the VHDL signal, a class for bit
-oriented operations, and support for enumeration types.  The Python
-\code{yield} statement is used as a general sensitivity list to wait
-on a signal change, an edge, a delay, or on the completion of another
-generator. \myhdl{} supports waveform viewing by tracing signal
-changes in a VCD file.
+\emph{Modeling}
 
-Python's rare combination of power and clarity makes it ideal for high
-level modeling.  It can be expected that \myhdl{} users will often
-have the ``Pythonic experience'' of finding an elegant solution to a
-complex modeling problem. Moreover, Python is outstanding for rapid
+
+Python's power and clarity make \myhdl{} an ideal solution for high level
+modeling. Python is famous for enabling elegant solutions to complex
+modeling problems. Moreover, Python is outstanding for rapid
 application development and experimentation.
 
+The key idea behind \myhdl{} is the use of Python generators to model
+hardware concurrency. Generators are best described as resumable
+functions. In \myhdl{}, generators are used in a specific way so that
+they become similar to always blocks in Verilog or processes in VHDL.
+
+A hardware module is modeled as a function that returns any number of
+generators. This approach makes it straightforward to support features
+such as arbitrary hierarchy, named port association, arrays of
+instances, and conditional instantiation.
+
+Furthermore, \myhdl{} provides classes that implement traditional
+hardware description concepts. It provides a signal class to support
+communication between generators, a class to support bit oriented
+operations, and a class for enumeration types.
+
+\emph{Simulation and Verification}
+
+The built-in simulator runs on top of the Python interpreter. It
+supports waveform viewing by tracing signal changes in a VCD file.
+
 With \myhdl{}, the Python unit test framework can be used on hardware
-designs.  \myhdl{} can also be used as hardware verification language for
-VHDL and Verilog designs, by co-simulation with any simulator that has
-a PLI.  The distribution contains a PLI module for the
-Icarus Verilog simulator.
+designs. Although unit testing is a popular modern software
+verification technique, it is not yet common in the hardware design
+world, making it one more area in which \myhdl{} innovates.
 
-Finally, a subset of \myhdl{} code can be converted automatically to
-synthesizable Verilog code. This feature provides a direct path from
-Python to an FPGA or ASIC implementation.
+\myhdl{} can also be used as hardware verification language for VHDL and
+Verilog designs, by co-simulation with traditional HDL simulators.
 
-The \myhdl{} software is open source software. It is licensed under the
-GNU Lesser General Public License (LGPL).
+\emph{Conversion to Verilog}
 
+The converter to Verilog works on an instantiated design that has been
+fully elaborated. Consequently, the original design structure can be
+arbitrarily complex.
+
+The converter automates certain tasks that are tedious or hard in
+Verilog directly. Notable features are the possibility to choose
+between various FSM state encodings based on a single attribute, the
+mapping of certain high-level objects to RAM and ROM descriptions, and
+the automated handling of signed arithmetic issues.
 
 
 

doc/manual/background.tex

@@ -3,14 +3,14 @@
 \section{Prerequisites \label{prerequisites}}
 
 You need a basic understanding of Python to use \myhdl{}.
-If you don't know Python, you will take comfort in knowing
-that it is probably one of the easiest programming languages to
+If you don't know Python, don't worry: it
+it is one of the easiest programming languages to
 learn~\footnote{You must be bored by such claims, but in Python's
-case it's true.}. Learning Python is also one of the better time
+case it's true.}. Learning Python is one of the best time
 investments that engineering professionals can make~\footnote{I am not
 biased.}.
 
-For beginners, \url{http://www.python.org/doc/current/tut/tut.html} is
+For starters, \url{http://www.python.org/doc/current/tut/tut.html} is
 probably the best choice for an on-line tutorial. For alternatives,
 see \url{http://www.python.org/doc/Newbies.html}.
 
@@ -94,7 +94,7 @@ until they are exhausted. What happens is that the
 \keyword{return}, except that it is non-fatal: the generator remembers
 its state and the point in the code when it yielded. A higher order
 agent can decide when to get a further value by calling the
-generator's \function{next()} method. We can say that generators are
+generator's \function{next()} method. We say that generators are
 \dfn{resumable functions}.
 
 If you are familiar with hardware description languages, this may ring
@@ -124,15 +124,15 @@ documentation, e.g. at \url{http://www.python.org/doc/2.2.2/whatsnew}.
 \section{About decorators \label{deco}}
 \index{decorators!about}
 
-Python 2.4 introduced a new feature called decorators. MyHDL 0.5 defines
-a number of decorators to facilitate hardware descriptions, but many users may
-not be familiar with the concept. Therefore, an introduction
-is included here.
+Python 2.4 introduced a new feature called decorators. MyHDL 0.5 takes
+advantage of this new feature by defining a number of decorators that
+facilitate hardware descriptions. However, many users may not yet be familiar with
+decorators. Therefore, an introduction is included here.
 
 A decorator consists of special syntax in front of a function
-declaration. It refers to a decorator function. The decorator
-function automatically transforms the declared function into some
-other callable object.
+declaration. It refers to a decorator function. The decorator function
+automatically transforms the declared function into some other
+callable object.
 
 A decorator function \function{deco} is used in a decorator statement as follows:
 
@@ -150,10 +150,10 @@ func = deco(func)
 
 Note that the decorator statement goes directly in front of the
 function declaration, and that the function name func is automatically
-reused.
+reused for the final result.
 
 MyHDL 0.5 uses decorators to create ready-to-simulate generators
-from local (embedded) function definitions. Their functionality
+from local function definitions. Their functionality
 and usage will be described extensively in this manual.
 
 For more info about Python decorators, consult the on-line Python

doc/manual/intro.tex

@@ -50,19 +50,20 @@ classic functions are used to model hardware modules. In particular,
 the parameter list is used to define the interface. In this first
 example, the interface is empty.
 
-Inside the top level function we declared a local function called
+Inside the top level function we declare a local function called
 \function{sayHello} that defines the desired behavior. This function
-is decorated with an \function{@always} decorator that has a delay
+is decorated with an \function{always} decorator that has a delay
+   \index{decorator!\function{always}}
 object as its parameter.  The meaning is that the function will be
 executed whenever the specified delay interval has expired.
 
-Behind the curtains, the \function{@always} decorator creates a Python
+Behind the curtains, the \function{always} decorator creates a Python
 \emph{generator} and reuses the name of the decorated function for
 it. Generators are the fundamental objects in MyHDL, and we will say
 much more about them further on.
 
-Finally, the top level function returns the local generator. This code
-pattern is the simplest incarnation of the basic MyHDL code pattern
+Finally, the top level function returns the local generator. This is
+the simplest case of the basic MyHDL code pattern
 to define the contents of a hardware module. We will describe the
 general case further on.
 
@@ -74,20 +75,20 @@ then run the simulation for the desired amount of timesteps.
 
 \section{Signals, ports, and concurrency \label{intro-conc}}
 
-In the previous section, we simulated a design that consisted
-of a single generator. Of course,
-real hardware descriptions are not like that: they are
-typically massively concurrent. \myhdl\ supports this by allowing an
-arbitrary number of concurrent generators. 
+In the previous section, we simulated a design with a single
+generator and no concurrency. On the other hand, real hardware
+descriptions typically have massive concurrency.
+\myhdl\ supports this by allowing an
+arbitrary number of concurrently running generators. 
 
 With concurrency comes the problem of deterministic
 communication. Hardware languages use special objects to
 support deterministic communication between concurrent code.
-For this purpose \myhdl\
+In particular, \myhdl\ 
 has a \class{Signal} object which is roughly modeled after VHDL
 signals.
 
-We will demonstrate the use of signals and the concept of concurrency
+We will demonstrate signals and concurrency
 by extending and modifying our first example. We define two hardware
 modules, one that drives a clock signal, and one that is sensitive
 to a positive edge on a clock signal:
@@ -142,14 +143,14 @@ Its generator is made sensitive to a rising
     \index{wait!for a rising edge}%
 edge of the clock signal. This is specified by the
 \code{posedge} attribute of a signal. The edge
-specifier is the argument of the \code{@always}
+specifier is the argument of the \code{always}
 decorator. As a result, the decorated function
 will be executed on every rising clock edge.
 
 The \code{clk} signal is constructed with an initial value
-\code{0}. When creating an instance of each to the two
-hardware modules, the same clock signal is passed as
-the argument. The result is that the two instances
+\code{0}. When creating an instance of each 
+hardware module, the same clock signal is passed as
+the argument. The result is that the instances
 are now connected through the clock signal.
 The \class{Simulation} object is constructed with the
 two instances.
@@ -198,16 +199,17 @@ In addition to the clock signal, the clock
 \var{period} is a parameter with a default value of \code{20}.
 
 As the low time of the clock may differ from the high time in case of
-an odd period, we cannot use the \function{@always} decorator with a
+an odd period, we cannot use the \function{always} decorator with a
 single delay value anymore. Instead, the \function{driveClk} function
 is now a generator function with an explicit definition of the desired
-behavior. You can see that \function{driveClk} is a generator function (as
-opposed to a classic function) because it contains \code{yield}
-statements.
+behavior and decorated with the \function{instance} decorator.
+    \index{decorator!\function{instance}}
+You can see that \function{driveClk} is a generator function
+because it contains \code{yield} statements.
 
-When a generator function is called, it returns a generator object. In
-fact, this is mainly what the \function{@instance} decorator does. It
-is less sophisticated than the \function{@always} decorator,
+When a generator function is called, it returns a generator object.
+This is basically what the \function{instance} decorator does. It
+is less sophisticated than the \function{always} decorator,
 but it can be used to create a generator from any local generator
 function.
 
@@ -322,7 +324,7 @@ desired features, but lacks support for indexing and slicing. For this
 reason, \myhdl\ provides the \class{intbv} class. The name was chosen
 to suggest an integer with bit vector flavor.
 
-Class \class{intbv} works transparently as an integer and with other
+Class \class{intbv} works transparently with other
 integer-like types. Like class \class{int}, it provides access to the
 underlying two's complement representation for bitwise
 operations. In addition, it is a mutable type that provides indexing
@@ -358,14 +360,15 @@ This code introduces a few new concepts. The string in triple quotes
 at the start of the function is a \dfn{doc string}. This is standard
 Python practice for structured documentation of code.
 
-Furthermore, we introduce a third decorator: \function{@always_comb}.
+Furthermore, we introduce a third decorator: \function{always_comb}.
+    \index{decorator!\function{always_comb}}
 It is used with a classic function and specifies that the 
 resulting generator should
     \index{wait!for a signal value change}%
 wait for a value change on any input signal. This is typically used to
 describe 
     \index{combinatorial logic}%
-combinatorial logic. The \function{@always_comb} decorator
+combinatorial logic. The \function{always_comb} decorator
 automatically infers which signals are used as inputs.
 
 Finally, the code contains bit indexing operations and an exclusive-or
@@ -517,7 +520,7 @@ Here is an overview of what we have learned in this chapter:
 
 \begin{itemize}
 \item Generators are the basic building blocks of MyHDL models. They
-provide massive light-weight concurrency, and a way to model sensitivity lists.
+provide the way to model massive concurrency and sensitiviy lists.
 
 \item MyHDL provides decorators that create useful generators from local functions.
 
@@ -548,6 +551,6 @@ languages such as Verilog and VHDL. This is described in
 Chapter~\ref{cosim}.
 
 \item Last but not least, MyHDL models can be converted to
-Verilog as a path to a silicon implementation. This
+Verilog, providing a path to a silicon implementation. This
 is the topic of Chapter~\ref{conv}.
 \end{itemize}