Added

myhdl/Simulation_spec.txt

@@ -84,12 +84,13 @@ Specification for the Simulation class
     the generator should run at the rising or falling edge on a
     signal.
   - a join object. This specifies that the generator should run when
-    all arguments of the join have triggered.
+    all arguments of the join have triggered. A join argument can be
+    any of the trigger argument described int this list.
   - a generator. In this case, the generator is dynamically added to
     the list of generators to be run in the timestep. When the
     generator completes, the orginal generator is triggered.
 
 * When there are no further events, the Simulation.run method raises
-  the StopSimulationn exception.
+  the StopSimulation exception.
 
 

myhdl/intbv_spec.txt

@@ -0,0 +1,81 @@
+#  This file is part of the myhdl library, a Python package for using
+#  Python as a Hardware Description Language.
+#
+#  Copyright (C) 2003 Jan Decaluwe
+#
+#  The myhdl library is free software; you can redistribute it and/or
+#  modify it under the terms of the GNU Lesser General Public License as
+#  published by the Free Software Foundation; either version 2.1 of the
+#  License, or (at your option) any later version.
+#
+#  This library is distributed in the hope that it will be useful, but
+#  WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+#  Lesser General Public License for more details.
+
+#  You should have received a copy of the GNU Lesser General Public
+#  License along with this library; if not, write to the Free Software
+#  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+__author__ = "Jan Decaluwe <jan@jandecaluwe.com>"
+__version__ = "$Revision$"
+__date__ = "$Date$"
+
+Specification for the intbv class
+---------------------------------
+
+Hardware description languages need bit-oriented data types. The
+standard Python int and long types have most of the desired features,
+including bitwise operations and an underlying 2-s complement
+representation, except one: mutability. Hardware designers want to be
+able to set bits and slices of a bit vector. The intbv class provides
+such a mutable number. It is designed to work transparently as a
+number, with other intbv's and with ints and longs. In addition, it
+has indexing and slicing operations and a few other bit-oriented
+features. As it is mutable, it cannot be a subtype of int; so it is a
+separate type.
+
+* an intbv(arg) constructor takes and int, long, intbv, or bit string
+  as its argument. The bit string works as in int(bit string, 2).
+
+* an intbv supports the same the numeric, comparison, bitwise and
+  conversion operators as ints and longs. It supports mixed-type
+  operations with ints and longs, that always return an intbv.
+
+* an intbv supports indexing operations, both to get and set a bit.
+
+* an intbv supports slicing operations, both to get and set a
+  slice. As is customary in hardware design, and unlike Python
+  sequences, the rightmost bit has index 0, and a slice is taken by a
+  downward range; in other words, in [i:j], i has to be larger than
+  j. People may object to this as it departs from standard Python
+  sequence conventions. However, an intbv should not be seen as a
+  sequence, but as a number in the first place: the indexing/slicing
+  operations are borrowed to get/set individual bits in a number. It
+  seems natural that the index of a bit should equal the power of the
+  corresponding 2**i term in a representation of the number's value as
+  a sum of powers of 2. This is also the standard hardware design way
+  to look at it.
+
+* As in standard Python, ranges are half-open; however, the
+  not-included index is the left index. Only the right index can be
+  left unspecified and defaults to zero: in that case the left index
+  is equals the number of bits taken. Provided the downward range
+  concept is accepted, this seems like the Pythonic way to do it. Just
+  like with sequences, this convention avoids one-off issues in a lot
+  of practical cases.
+
+* When setting slices, there should be check on the input value to
+  verify that all significant bits can be accepted by the slice.
+
+* intbv has a concat method that can concatenate intbv arguments. It
+  may be clearest to use this as an unbound method. The first argument
+  can be any intbv. However, for subsequent arguments there has to be
+  some way to derive the amount of bits. Therefore, the intbv returned
+  by an indexing or slicing operation should remember how many bits
+  were taken, so that they can be using in concatenations. In
+  addition, literal bit strings are accepted in concatenations, just as
+  they are in intbv contructors.
+
+* intbv supports the iterator protocol to iterate on its bits; again,
+  this requires a known length.