diff --git a/doc/manual/MyHDL.tex b/doc/manual/MyHDL.tex index ddd00e99..218445cb 100644 --- a/doc/manual/MyHDL.tex +++ b/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. diff --git a/doc/manual/background.tex b/doc/manual/background.tex index dea204fa..c52fd419 100644 --- a/doc/manual/background.tex +++ b/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 diff --git a/doc/manual/intro.tex b/doc/manual/intro.tex index 69ae02ff..fa3a9f5c 100644 --- a/doc/manual/intro.tex +++ b/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}