diff --git a/doc/manual/reference.tex b/doc/manual/reference.tex index f810f149..d20a9433 100644 --- a/doc/manual/reference.tex +++ b/doc/manual/reference.tex @@ -15,7 +15,7 @@ nested sequence.) See section~\ref{ref-gen} for the definition of \myhdl\ generators and their interaction with a \class{Simulation} object. -As a special case, exactly one of the ``generators'' may be +As a special case, exactly one of the arguments may be a \class{Cosimulation} object (see Section~\ref{ref-cosim}). \end{classdesc} @@ -36,17 +36,31 @@ Return the current simulation time. \end{funcdesc} \begin{excclassdesc}{StopSimulation}{} -Base exception that is caught by the \code{Simulation.run} method to +Base exception that is caught by the \code{Simulation.run()} method to stop a simulation. \end{excclassdesc} -\begin{funcdesc}{traceSignals}{genfunc \optional{, *args} \optional{, *kwargs}} +\begin{funcdesc}{traceSignals}{func \optional{, *args} \optional{, *kwargs}} +Enables signal tracing to a VCD file for waveform viewing. +\var{func} is a function that returns a nested sequence of +generators that represents an instance +hierarchy. \function{traceSignals()} call \var{func} under its control +and passes \var{*args} and \var{**kwargs} to the call. In this way, it +finds the hierarchy and the signals to be traced. +The return value is the same as would be returned by the call +\code{func(*args, *kwargs)}. It should be assigned +to a top level instance name. For example: +\begin{verbatim} +topname = traceSignals(func, ...) +\end{verbatim} +The resulting VCD file will be named after the top level instance +name. In the example, it would be called \file{topname.vcd}. If the +VCD file exists already, it will be moved to a backup file by +attaching a timestamp to it, before creating the new file. \end{funcdesc} - - \section{The \class{Signal} class \label{ref-sig}} \declaremodule{}{myhdl} @@ -77,7 +91,15 @@ attribute of another Signal object, its current value is assigned instead. \end{memberdesc} - +\begin{memberdesc}[Signal]{min} +Read-only attribute that is the minimum value (inclusive) of a +numeric signal, or \var{None} for no minimum. +\end{memberdesc} +\begin{memberdesc}[Signal]{max} +Read-only attribute that is the maximum value +(exclusive) of a numeric signal, or \var{None} for no +maximum. +\end{memberdesc} \section{\myhdl\ generators and trigger objects \label{ref-gen}} \declaremodule{}{myhdl} @@ -161,7 +183,11 @@ immediately. \declaremodule{}{myhdl} \begin{funcdesc}{always_comb}{func} - +Returns a generator that is sensitive to all signals that +are used as inputs in function \function{func()}. The generator +will run \function{func()} whenever one of the inputs changes. +\function{func} should be a locally defined function without +parameters. \end{funcdesc} \begin{funcdesc}{bin}{num \optional{, width}} @@ -175,17 +201,15 @@ needed in hardware design. \end{funcdesc} \begin{funcdesc}{concat}{base \optional{, arg \moreargs}} -Concatenate the arguments to an \class{intbv} object. Naturally, the -concatenation arguments need to have a defined bit width. Therefore, -if they are \class{intbv} objects, they have to be the return values -of a slicing operation. Alternatively, they may be bit strings. +Returns an \class{intbv} object by concatenating its arguments. -In contrast to all other arguments, the implicit \var{self} argument -doesn't need to have a defined bit with. This is due to the fact that -concatenation occurs at the lsb (rightmost) side. - -It may be clearer to call this method as an unbound method with an -explicit first \class{intbv} argument. +The following argument types are supported: \class{intbv} objects with +a defined bit width, \class{bool} objects, signals of the previous +objects, and bit strings. All these objects have a defined bit +width. The first argument \var{base} is special as it doesn't need to +have a defined bit width. In addition to the previously mentioned +objects, \class{intbv}, \class{int} and \class{long} objects +are supported, as well as signals of such objects. \end{funcdesc} \begin{funcdesc}{downrange}{high \optional{, low=0}} @@ -198,7 +222,7 @@ defaults to zero. This function is especially useful in conjunction with the \class{intbv} class, that also works with downward indexing. \end{funcdesc} -\begin{funcdesc}{enum}{arg \optional{,arg \moreargs}} +\begin{funcdesc}{enum}{arg \optional{, arg \moreargs}} \end{funcdesc} diff --git a/doc/whatsnew03/whatsnew03.tex b/doc/whatsnew03/whatsnew03.tex index 0f1cd592..d9286be6 100644 --- a/doc/whatsnew03/whatsnew03.tex +++ b/doc/whatsnew03/whatsnew03.tex @@ -322,7 +322,7 @@ example: '0xfab4' \end{verbatim} -\class{intbv} instances now have \var{min} and \var{max} attributes +\class{intbv} objects now have \var{min} and \var{max} attributes that can be specified at construction time. The meaning is that that only values within \code{range(min, max)} are permitted. The default values for these attributes is \var{None}, meaning ``infinite''. For @@ -349,9 +349,9 @@ Traceback (most recent call last): ValueError: intbv value 53 >= maximum 53 \end{verbatim} -When a slice is taken from an \class{intbv} instance, the return value -is a new \class{intbv} instance with a defined bit width. As in -Verilog, the value of the new \class{intbv} instance is always +When a slice is taken from an \class{intbv} object, the return value +is a new \class{intbv} object with a defined bit width. As in +Verilog, the value of the new \class{intbv} object is always positive, regardless of the sign of the original value. In addition, the \var{min} and \var{max} attributes are set implicitly: @@ -368,7 +368,7 @@ intbv(0) Lastly, a small change was implemented with regard to binary operations. In previous versions, both numeric and bit-wise operations always returned a new \class{intbv} -instance, even in mixed-mode operations with \class{int} +object, even in mixed-mode operations with \class{int} objects. This has changed: numeric operations return an \class{int}, and bitwise operations return a \class{intbv}. In this way, the return value corresponds @@ -382,14 +382,13 @@ available. Instead, there is now a \function{concat()} function in \myhdl{}. A function is more natural because \myhdl\ objects of various types -can be concatenated. In addition to \class{intbv} instances, this -includes objects with a defined bit width, such as bit strings, -\class{bool} variables, and \class{Signal} instances of such -objects. Moreover, the first argument to \function{concat()} can be an -\class{int} or a \class{long}, or a the corresponding \class{Signal} -instance. As a result, the \function{concat()} function supports a -much broader range of objects than a method could. Function -\function{concat()} returns an \class{intbv} instance. +can be concatenated. In addition to \class{intbv} objects, this +includes objects with a defined bit width, \class{bool} objectsm +signals of such objects, and bit strings. Moreover, the first argument +to \function{concat()} can be an \class{int} or a \class{long}, or a +the corresponding signal. As a result, the \function{concat()} +function supports a much broader range of objects than a method could. +Function \function{concat()} returns an \class{intbv} object. \section{Python 2.3 support\label{section-Python}} diff --git a/myhdl/Signal_spec.txt b/myhdl/Signal_spec.txt index c4a3ee9d..fa424f52 100644 --- a/myhdl/Signal_spec.txt +++ b/myhdl/Signal_spec.txt @@ -30,7 +30,7 @@ part of the public interface of the Signal class. The private attributes and methods are for internal use or for use by a simulator object that interacts with Signal objects. -In the following, a "sig" denotes an instance of the Signal class. +In the following, a "sig" denotes an object of the Signal class. * A sig should have a read-only attribute 'val' that represents its current value. diff --git a/myhdl/intbv_spec.txt b/myhdl/intbv_spec.txt index cf89da66..a296d4bb 100644 --- a/myhdl/intbv_spec.txt +++ b/myhdl/intbv_spec.txt @@ -75,9 +75,9 @@ separate type. * When setting slices, there should be check on the input value to verify that all significant bits can be accepted by the slice. -* When getting as slice, the result is a new intbv instance. Its +* When getting as slice, the result is a new intbv object. Its value is always positive or zero, regardless of the sign of the - original intbv instances. When the left index is specified, the + original intbv object. When the left index is specified, the new intbv has a defined bitwidth w=i-j. The min and max attributes of the new intbv are implicitly set to 0 and 2**w respectively.