1
0
mirror of https://github.com/myhdl/myhdl.git synced 2025-01-24 21:52:56 +08:00

proofreading

This commit is contained in:
jand 2005-12-27 11:27:05 +00:00
parent d911dacf4f
commit cf93480199
3 changed files with 93 additions and 74 deletions

View File

@ -21,47 +21,63 @@
\noindent \noindent
\myhdl{} is a Python package for using Python as a hardware description The goal of the \myhdl{} project is to empower hardware designers with
and verification language. Languages such Verilog and VHDL are the elegance and simplicity of the Python language.
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 key idea behind \myhdl{} is to use Python generators for modeling \myhdl{} is a free, open-source (LGPL) package for using Python as a
hardware concurrency. A generator is a resumable function with hardware description and verification language. Python is a very high
internal state. In \myhdl{}, a hardware module is modeled as a function level language, and hardware designers can use its full power to model
that returns generators. With this approach, \myhdl{} directly supports and simulate their designs. Moreover, \myhdl{} can convert a design to
features such as named port association, arrays of instances, and Verilog. In combination with an external synthesis tool, it provides a
conditional instantiation. complete path from Python to a silicon implementation.
\myhdl{} supports the classic hardware description concepts. It \emph{Modeling}
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.
Python's rare combination of power and clarity makes it ideal for high
level modeling. It can be expected that \myhdl{} users will often Python's power and clarity make \myhdl{} an ideal solution for high level
have the ``Pythonic experience'' of finding an elegant solution to a modeling. Python is famous for enabling elegant solutions to complex
complex modeling problem. Moreover, Python is outstanding for rapid modeling problems. Moreover, Python is outstanding for rapid
application development and experimentation. 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 With \myhdl{}, the Python unit test framework can be used on hardware
designs. \myhdl{} can also be used as hardware verification language for designs. Although unit testing is a popular modern software
VHDL and Verilog designs, by co-simulation with any simulator that has verification technique, it is not yet common in the hardware design
a PLI. The distribution contains a PLI module for the world, making it one more area in which \myhdl{} innovates.
Icarus Verilog simulator.
Finally, a subset of \myhdl{} code can be converted automatically to \myhdl{} can also be used as hardware verification language for VHDL and
synthesizable Verilog code. This feature provides a direct path from Verilog designs, by co-simulation with traditional HDL simulators.
Python to an FPGA or ASIC implementation.
The \myhdl{} software is open source software. It is licensed under the \emph{Conversion to Verilog}
GNU Lesser General Public License (LGPL).
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.

View File

@ -3,14 +3,14 @@
\section{Prerequisites \label{prerequisites}} \section{Prerequisites \label{prerequisites}}
You need a basic understanding of Python to use \myhdl{}. You need a basic understanding of Python to use \myhdl{}.
If you don't know Python, you will take comfort in knowing If you don't know Python, don't worry: it
that it is probably one of the easiest programming languages to it is one of the easiest programming languages to
learn~\footnote{You must be bored by such claims, but in Python's 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 investments that engineering professionals can make~\footnote{I am not
biased.}. 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, probably the best choice for an on-line tutorial. For alternatives,
see \url{http://www.python.org/doc/Newbies.html}. 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 \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 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 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}. \dfn{resumable functions}.
If you are familiar with hardware description languages, this may ring 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}} \section{About decorators \label{deco}}
\index{decorators!about} \index{decorators!about}
Python 2.4 introduced a new feature called decorators. MyHDL 0.5 defines Python 2.4 introduced a new feature called decorators. MyHDL 0.5 takes
a number of decorators to facilitate hardware descriptions, but many users may advantage of this new feature by defining a number of decorators that
not be familiar with the concept. Therefore, an introduction facilitate hardware descriptions. However, many users may not yet be familiar with
is included here. decorators. Therefore, an introduction is included here.
A decorator consists of special syntax in front of a function A decorator consists of special syntax in front of a function
declaration. It refers to a decorator function. The decorator declaration. It refers to a decorator function. The decorator function
function automatically transforms the declared function into some automatically transforms the declared function into some other
other callable object. callable object.
A decorator function \function{deco} is used in a decorator statement as follows: 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 Note that the decorator statement goes directly in front of the
function declaration, and that the function name func is automatically 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 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. and usage will be described extensively in this manual.
For more info about Python decorators, consult the on-line Python For more info about Python decorators, consult the on-line Python

View File

@ -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 the parameter list is used to define the interface. In this first
example, the interface is empty. 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 \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 object as its parameter. The meaning is that the function will be
executed whenever the specified delay interval has expired. 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 \emph{generator} and reuses the name of the decorated function for
it. Generators are the fundamental objects in MyHDL, and we will say it. Generators are the fundamental objects in MyHDL, and we will say
much more about them further on. much more about them further on.
Finally, the top level function returns the local generator. This code Finally, the top level function returns the local generator. This is
pattern is the simplest incarnation of the basic MyHDL code pattern the simplest case of the basic MyHDL code pattern
to define the contents of a hardware module. We will describe the to define the contents of a hardware module. We will describe the
general case further on. 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}} \section{Signals, ports, and concurrency \label{intro-conc}}
In the previous section, we simulated a design that consisted In the previous section, we simulated a design with a single
of a single generator. Of course, generator and no concurrency. On the other hand, real hardware
real hardware descriptions are not like that: they are descriptions typically have massive concurrency.
typically massively concurrent. \myhdl\ supports this by allowing an \myhdl\ supports this by allowing an
arbitrary number of concurrent generators. arbitrary number of concurrently running generators.
With concurrency comes the problem of deterministic With concurrency comes the problem of deterministic
communication. Hardware languages use special objects to communication. Hardware languages use special objects to
support deterministic communication between concurrent code. support deterministic communication between concurrent code.
For this purpose \myhdl\ In particular, \myhdl\
has a \class{Signal} object which is roughly modeled after VHDL has a \class{Signal} object which is roughly modeled after VHDL
signals. 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 by extending and modifying our first example. We define two hardware
modules, one that drives a clock signal, and one that is sensitive modules, one that drives a clock signal, and one that is sensitive
to a positive edge on a clock signal: 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}% \index{wait!for a rising edge}%
edge of the clock signal. This is specified by the edge of the clock signal. This is specified by the
\code{posedge} attribute of a signal. The edge \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 decorator. As a result, the decorated function
will be executed on every rising clock edge. will be executed on every rising clock edge.
The \code{clk} signal is constructed with an initial value The \code{clk} signal is constructed with an initial value
\code{0}. When creating an instance of each to the two \code{0}. When creating an instance of each
hardware modules, the same clock signal is passed as hardware module, the same clock signal is passed as
the argument. The result is that the two instances the argument. The result is that the instances
are now connected through the clock signal. are now connected through the clock signal.
The \class{Simulation} object is constructed with the The \class{Simulation} object is constructed with the
two instances. 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}. \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 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 single delay value anymore. Instead, the \function{driveClk} function
is now a generator function with an explicit definition of the desired is now a generator function with an explicit definition of the desired
behavior. You can see that \function{driveClk} is a generator function (as behavior and decorated with the \function{instance} decorator.
opposed to a classic function) because it contains \code{yield} \index{decorator!\function{instance}}
statements. 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 When a generator function is called, it returns a generator object.
fact, this is mainly what the \function{@instance} decorator does. It This is basically what the \function{instance} decorator does. It
is less sophisticated than the \function{@always} decorator, is less sophisticated than the \function{always} decorator,
but it can be used to create a generator from any local generator but it can be used to create a generator from any local generator
function. 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 reason, \myhdl\ provides the \class{intbv} class. The name was chosen
to suggest an integer with bit vector flavor. 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 integer-like types. Like class \class{int}, it provides access to the
underlying two's complement representation for bitwise underlying two's complement representation for bitwise
operations. In addition, it is a mutable type that provides indexing 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 at the start of the function is a \dfn{doc string}. This is standard
Python practice for structured documentation of code. 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 It is used with a classic function and specifies that the
resulting generator should resulting generator should
\index{wait!for a signal value change}% \index{wait!for a signal value change}%
wait for a value change on any input signal. This is typically used to wait for a value change on any input signal. This is typically used to
describe describe
\index{combinatorial logic}% \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. automatically infers which signals are used as inputs.
Finally, the code contains bit indexing operations and an exclusive-or 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} \begin{itemize}
\item Generators are the basic building blocks of MyHDL models. They \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. \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}. Chapter~\ref{cosim}.
\item Last but not least, MyHDL models can be converted to \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}. is the topic of Chapter~\ref{conv}.
\end{itemize} \end{itemize}