From c9d7f3206c57d910c7e060881206c671140fd6ff Mon Sep 17 00:00:00 2001 From: Guenter Dannoritzer Date: Mon, 25 Aug 2008 12:33:03 +0200 Subject: [PATCH 1/5] Added intbv.signed() documentation In the introductional section of the manual under bit oriented operations there is a new subsection describing the signed() member function of intbv. --- doc/source/manual/intro.rst | 112 +++++++++++++++++++++++++++++++++++- 1 file changed, 110 insertions(+), 2 deletions(-) diff --git a/doc/source/manual/intro.rst b/doc/source/manual/intro.rst index 85283f04..d514a006 100644 --- a/doc/source/manual/intro.rst +++ b/doc/source/manual/intro.rst @@ -450,8 +450,116 @@ one-off count issues in practice. For example, the slice ``hex[8:]`` has exactly about it as follows: for a slice ``[i:j]``, only bits below index ``i`` are included, and the bit with index ``j`` is the last bit included. -When an intbv object is sliced, a new intbv object is returned. This new intbv -object is always positive, even when the original object was negative. +When an :class:`intbv` object is sliced, a new :class:`intbv` object is returned. +This new :class:`intbv` object is always positive, even when the original object was negative. + +Take the following example of a range restricted :class:`intbv` +instance:: + + >>> a = intbv(6,min=-8,max=8) + >>> a._nrbits + 4 + >>> b = a[4:] + >>> b + intbv(6L) + >>> b.min + 0 + >>> b.max + 16 + >>> + +The value is set to 6 and the range to -8 to 7. Note that the max value +is excluded. Checking the bit width with the *_nrbits* attribute shows +that it occupies 4 bits. If we slice now all bits, by using the convention +a[4:], which means to slice the 4 lsb bits, the returned :class:`intbv` +instance will still have 4 bits, the value will not change, but the range +will be changed to min=0 and max=16. + +One thing to note here is that unlike bit width specified variables, +:class:`intbv` instances can be constructed with assymetric value range. + +Let's do a small variation to the above example:: + + >>> a = intbv(6,min=-4,max=8) + >>> a._nrbits + 4 + +The lower range got reduced to -4, but looking at the required number of +bits, there are still 4 bits necessary to represent the value range. + +Let's change that and increase the number range for the negative +numbers:: + + >>> a = intbv(6,min=-16,max=8) + >>> a._nrbits + 5 + +Here now 5 bits are necessary to represent the negative value range up +to -16. + + +.. _intro-signed: + +Conversion to signed representation +----------------------------------- + +.. index:: + single: intbv; signed() + single: intbv; min + single: intbv; max + single: intbv; _nrbits + + +When using the :class:`intbv` class with restricted bit width, the *min* and +*max* attributes can be used to restrict the value range. From a +:class:`intbv` instance with positve and negative value range we saw in +the previous section that it is possible to slice bits and the returned +:class:`intbv` instance will have a postive value range. In hardware +description it is sometimes desirable to have a bit vector with positive +value range and create from it a bit vector that allows positive and +negative value range. + +As an example let's take a 8-bit wide data bus that would be modeled as +follows:: + + intbv(0, min=0, max=256) + +Now consider that e.g. a complex number is transfered over this data +bus. The upper 4 bits of the data bus are used to transfer the real value and +the lower 4 bits for the imaginary value. As real and imaginary value +have a positive and negative value range, it would be good to have a way +to slice off bits and have them be considered of positive and negative +value range. The ``signed`` member function of the :class:`intbv` will +allow to do just that. + +The basic functionality of the ``signed`` member function is to classify +the value of :class:`intbv` as either 'signed' or 'unsigned', based on the +*min* and *max* values. If the value is classified as 'signed', the ``signed`` +member function will return the value unchanged as integer value. If it is +considered 'unsigned' the bits of the value, as specified by *_nrbits* are +considered a 2's complement number and returned as integer. That means +that if the msb is set, the value is considered negative and if the msb +is not set, it is considered a positive value. + +The classification is done based on the *min* and *max* attributes. The +value is classified as 'unsigned' if *min* >= 0 and *max* > *min*. In all +other cases the value is classified as 'signed'. + +Let's look at a basic example:: + + >>> a = intbv(12, min=0, max=16) + >>> bin(a) + '1100' + >>> b = a.signed() + >>> b + -4L + +A 4-bits wide :class:`intbv` instance is assigned the value 12. In +binary representation this is '1100', that means the msb is set. +The instance is create with min=0 and max=16, which qualifies it to be +classified as 'unsigned' by the ``signed`` function. The function call +will return the binary '1100' as 2's complement value, which is -4. Note +that the return type is a integer/long type. .. _intro-python: From c4aa7536876b7df137d36aac72bc498da57fd9bd Mon Sep 17 00:00:00 2001 From: Guenter Dannoritzer Date: Mon, 25 Aug 2008 13:38:20 +0200 Subject: [PATCH 2/5] Added reference for intbv.signed() Added reference documentation for the intbv.signed() member function. --- doc/source/manual/reference.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/doc/source/manual/reference.rst b/doc/source/manual/reference.rst index 80213c76..ebaa2094 100644 --- a/doc/source/manual/reference.rst +++ b/doc/source/manual/reference.rst @@ -349,6 +349,14 @@ attributes: Read-only attribute that is the maximum value (exclusive) of an :class:`intbv`, or *None* for no maximum. +.. method:: intbv.signed() + + Return the :class:`intbv` value as 2's complement number if the value is + classified as 'unsigned'. The value is classfied as 'unsigned' if the + *min* attribute is >= 0 and *max* > *min*. + + :rtype: integer + Unlike :class:`int` objects, :class:`intbv` objects are mutable; this is also the reason for their existence. Mutability is needed to support assignment to indexes and slices, as is common in hardware design. For the same reason, From b0205d400b5e48e66a2e4c490c0bfe0e08be9c26 Mon Sep 17 00:00:00 2001 From: Guenter Dannoritzer Date: Mon, 25 Aug 2008 23:05:10 +0200 Subject: [PATCH 3/5] Updated and added some index entries in the document Renamed the latest enum() entry in the index. Added new entry for concat() function. Fixed some wording in the bit slicing section. --- doc/source/manual/intro.rst | 8 +++++--- doc/source/manual/modeling.rst | 2 +- doc/source/manual/reference.rst | 5 +++++ 3 files changed, 11 insertions(+), 4 deletions(-) diff --git a/doc/source/manual/intro.rst b/doc/source/manual/intro.rst index d514a006..6408a7d4 100644 --- a/doc/source/manual/intro.rst +++ b/doc/source/manual/intro.rst @@ -410,7 +410,9 @@ The simulation produces the following output:: Bit slicing ----------- -.. index:: single: bit slicing +.. index:: + single: bit slicing + single: concat(); example usage For a change, we will use a traditional function as an example to illustrate slicing. The following function calculates the HEC byte of an ATM header. :: @@ -468,7 +470,7 @@ instance:: 16 >>> -The value is set to 6 and the range to -8 to 7. Note that the max value +The value is set to 6 and the range to -8 ... 7. Note that the max value is excluded. Checking the bit width with the *_nrbits* attribute shows that it occupies 4 bits. If we slice now all bits, by using the convention a[4:], which means to slice the 4 lsb bits, the returned :class:`intbv` @@ -494,7 +496,7 @@ numbers:: >>> a._nrbits 5 -Here now 5 bits are necessary to represent the negative value range up +Here now 5 bits are necessary to represent the negative value range down to -16. diff --git a/doc/source/manual/modeling.rst b/doc/source/manual/modeling.rst index c79be3df..f0024d6d 100644 --- a/doc/source/manual/modeling.rst +++ b/doc/source/manual/modeling.rst @@ -384,7 +384,7 @@ are defined. Also, the identifiers evaluate to integers, whereas a string representation of the identifiers would be preferable. To solve these issues, we need an *enumeration type*. -.. index:: single: enum +.. index:: single: enum(); example usage MyHDL supports enumeration types by providing a function :func:`enum`. The arguments to :func:`enum` are the string representations of the identifiers, and diff --git a/doc/source/manual/reference.rst b/doc/source/manual/reference.rst index ebaa2094..f004e151 100644 --- a/doc/source/manual/reference.rst +++ b/doc/source/manual/reference.rst @@ -438,6 +438,8 @@ Miscellaneous modeling support functions This function complements the standard Python conversion functions ``hex`` and ``oct``. A binary string representation is often useful in hardware design. + :rtype: string + .. function:: concat(base [, arg ...]) @@ -450,6 +452,7 @@ Miscellaneous modeling support functions the previously mentioned objects, unsized :class:`intbv`, :class:`int` and :class:`long` objects are supported, as well as signals of such objects. + :rtype: :class:`intbv` .. function:: downrange(high [, low=0]) @@ -484,6 +487,8 @@ Miscellaneous modeling support functions Looks up all MyHDL instances in the local name space and returns them in a list. + :rtype: list + .. _ref-cosim: From 0cd710da2cd538410a78b174be43143fb974578f Mon Sep 17 00:00:00 2001 From: Guenter Dannoritzer Date: Tue, 26 Aug 2008 12:53:58 +0200 Subject: [PATCH 4/5] Extended intbv.signed() documentation Added example of intbv.signed() with slice. Moved index entries for intbv.min, .max, and ._nrbits up to the bit slicing section. Reworded the intbv.signed() description --- doc/source/manual/intro.rst | 43 ++++++++++++++++++++------------- doc/source/manual/reference.rst | 7 +++--- 2 files changed, 30 insertions(+), 20 deletions(-) diff --git a/doc/source/manual/intro.rst b/doc/source/manual/intro.rst index 6408a7d4..2fd38adf 100644 --- a/doc/source/manual/intro.rst +++ b/doc/source/manual/intro.rst @@ -452,6 +452,11 @@ one-off count issues in practice. For example, the slice ``hex[8:]`` has exactly about it as follows: for a slice ``[i:j]``, only bits below index ``i`` are included, and the bit with index ``j`` is the last bit included. +.. index:: + single: intbv; min + single: intbv; max + single: intbv; _nrbits + When an :class:`intbv` object is sliced, a new :class:`intbv` object is returned. This new :class:`intbv` object is always positive, even when the original object was negative. @@ -507,24 +512,20 @@ Conversion to signed representation .. index:: single: intbv; signed() - single: intbv; min - single: intbv; max - single: intbv; _nrbits When using the :class:`intbv` class with restricted bit width, the *min* and -*max* attributes can be used to restrict the value range. From a -:class:`intbv` instance with positve and negative value range we saw in -the previous section that it is possible to slice bits and the returned -:class:`intbv` instance will have a postive value range. In hardware -description it is sometimes desirable to have a bit vector with positive -value range and create from it a bit vector that allows positive and -negative value range. +*max* attributes are used to restrict the value range. From a :class:`intbv` +instance with positve and negative value range we saw in the previous section +that it is possible to slice bits and the returned :class:`intbv` instance +will have a postive value range. In hardware description it is sometimes +desirable to have a bit vector with positive value range and create from it +a bit vector that allows positive and negative value range. As an example let's take a 8-bit wide data bus that would be modeled as follows:: - intbv(0, min=0, max=256) + data_bus = intbv(0, min=0, max=256) Now consider that e.g. a complex number is transfered over this data bus. The upper 4 bits of the data bus are used to transfer the real value and @@ -539,9 +540,10 @@ the value of :class:`intbv` as either 'signed' or 'unsigned', based on the *min* and *max* values. If the value is classified as 'signed', the ``signed`` member function will return the value unchanged as integer value. If it is considered 'unsigned' the bits of the value, as specified by *_nrbits* are -considered a 2's complement number and returned as integer. That means +considered a two's complement number and returned as integer. That means that if the msb is set, the value is considered negative and if the msb -is not set, it is considered a positive value. +is not set, it is considered a positive value. The msb is here specified +by *_nrbits*-1. The classification is done based on the *min* and *max* attributes. The value is classified as 'unsigned' if *min* >= 0 and *max* > *min*. In all @@ -558,10 +560,17 @@ Let's look at a basic example:: A 4-bits wide :class:`intbv` instance is assigned the value 12. In binary representation this is '1100', that means the msb is set. -The instance is create with min=0 and max=16, which qualifies it to be -classified as 'unsigned' by the ``signed`` function. The function call -will return the binary '1100' as 2's complement value, which is -4. Note -that the return type is a integer/long type. +The instance is create with min=0 and max=16, which qualifies it for the +value to be classified as 'unsigned' by the ``signed`` function. The function +call will return the binary '1100' as two's complement value, which is -4. +Note that the return type is a integer type. + +To come back to the initial data bus example, the ``signed`` function +can be used in connection with a slice to slice the real and the +imaginary part from the data bus as follows: + + real = data_bus[].signed() + imag = data_bus[].signed() .. _intro-python: diff --git a/doc/source/manual/reference.rst b/doc/source/manual/reference.rst index f004e151..691a9dc1 100644 --- a/doc/source/manual/reference.rst +++ b/doc/source/manual/reference.rst @@ -351,9 +351,10 @@ attributes: .. method:: intbv.signed() - Return the :class:`intbv` value as 2's complement number if the value is - classified as 'unsigned'. The value is classfied as 'unsigned' if the - *min* attribute is >= 0 and *max* > *min*. + Return the bits as specified by the *_nrbits* attribute of the :class:`intbv` + value as two's complement number when classified as 'unsigned'. The value is + classfied as 'unsigned' if the *min* attribute is >= 0 and *max* > *min*. + Bit # *_nrbits*-1 specifies then the sign of the value. :rtype: integer From 5ebb299b71aa007d9ae083b9e1922a2bd5cd54b1 Mon Sep 17 00:00:00 2001 From: Guenter Dannoritzer Date: Tue, 26 Aug 2008 14:24:53 +0200 Subject: [PATCH 5/5] Fixed some typing mistakes --- doc/source/manual/intro.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/source/manual/intro.rst b/doc/source/manual/intro.rst index 2fd38adf..2e804e55 100644 --- a/doc/source/manual/intro.rst +++ b/doc/source/manual/intro.rst @@ -483,7 +483,7 @@ instance will still have 4 bits, the value will not change, but the range will be changed to min=0 and max=16. One thing to note here is that unlike bit width specified variables, -:class:`intbv` instances can be constructed with assymetric value range. +:class:`intbv` instances can be constructed with asymmetric value range. Let's do a small variation to the above example:: @@ -507,22 +507,22 @@ to -16. .. _intro-signed: -Conversion to signed representation ------------------------------------ +Unsigned to signed conversion +----------------------------- .. index:: single: intbv; signed() When using the :class:`intbv` class with restricted bit width, the *min* and -*max* attributes are used to restrict the value range. From a :class:`intbv` -instance with positve and negative value range we saw in the previous section +*max* attributes are used to restrict the value range. From an :class:`intbv` +instance with positive and negative value range we saw in the previous section that it is possible to slice bits and the returned :class:`intbv` instance -will have a postive value range. In hardware description it is sometimes +will have a positive value range. In hardware description it is sometimes desirable to have a bit vector with positive value range and create from it a bit vector that allows positive and negative value range. -As an example let's take a 8-bit wide data bus that would be modeled as +As an example let's take a 8 bit wide data bus that would be modeled as follows:: data_bus = intbv(0, min=0, max=256) @@ -558,7 +558,7 @@ Let's look at a basic example:: >>> b -4L -A 4-bits wide :class:`intbv` instance is assigned the value 12. In +A 4 bits wide :class:`intbv` instance is assigned the value 12. In binary representation this is '1100', that means the msb is set. The instance is create with min=0 and max=16, which qualifies it for the value to be classified as 'unsigned' by the ``signed`` function. The function