[myhdl-list] fixed-point MEP submitted (and more)

[Christopher F. <chr...@gm...>]

While moving the MEPs to the new development zone I added the
fixbv MEP-111 [1].  The following are some additional comments
or clarifications (differences) from the previous conversations.
Warning the following is fairly long but it is broken into
sections.


comparison (equality) operators
===============================
In the previous mailing-list discussion I did not mention the
comparison (equality?) operators.  Just like the add and
subtract operators the /fixbv/ point needs to be aligned for
comparisons, example:

     x = fixbv(.25, min=-8, max=8, res=1/256.)
     y = fixbv(.5, min=-8, max=8, res=1/256.)
     z = fixbv(.0, min=-8, max=8, res=1/512.)
     z[:] = x * y
     print(x > z)

At the point of the print: x=.25, y=.5, z=.125, without
alignment checks 'z' will evaluate greater than 'x'.
The equality operators need to check for point alignment.

This is true for all equality operators: '>', '<', '<=',
'>=', '!=', etc.  If the "point" is not aligned an
exception will be thrown (same as add and subtract).

This was not covered in the initial conversations or the
first version of the MEP (I will update).


fixbv initial value overflow and rounding
=========================================
Originally I proposed the following arguments for the fixbv

     fixbv(val, min, max, res, overflow_mode, round_mode)

I am removing the /overflow_mode/ and /round_mode/.  The
overflow, for the initial value will be handled the same as
the intbv.  If the value is out of range an exception will
be thrown (this is actually checked by the intbv.handleBounds).
This makes sense for an initial condition.

The round will be a normal (standard) round.  If a different
round is desired the (future) /resize/ or some other method
can be used, example:

     x = fixbv(0, min=-8, max=8, res=1/256.)
     x[:] = resize(4.332, x, round_mode='convergent')


precision vs. resolution
========================
I used resolution (res) in the initialization.  Resolution is
an appropriate term (from google dict)

     resolution: the smallest interval measurable by a
                 scientific (esp. optical) instrument; the
                 resolving power.

This is exactly what is being defined and [2] defines precision
as

     precision: exactness, the maximum number of non-zero bits
                representable.  Fixed-point the precision is
                the word-length.

[2] also uses the same definition for resolution as above.
I wanted to restate the definitions to clear-up any
possible confusion.   Other references are not as explicit
or consistent in the usage including [3] and [4].


negative indices
================
This has been mentioned and/or discussed in other threads.
I did not include negative indices in the initial proposal.
I do see a limited case where negative indices can be used
but I think a more explicit (and not limiting, I think) is
to retrieve the integer part or the fractional part.  In
the MEP I proposed functions similar to the intbv.signed

     fixbv.int()
     fixbv.frac()
     fixbv.ord()

For conversion it would be nice to also support int(fixbv)
and ord(fixbv) but I think that will be a future enhancement.
The supported conversion utilities will be the above.  See
the next section for more information on ord().


int() and ord()
===============
It was suggested that int() return just the integer portion
(makes sense) and I added ord() to return the "ordinal"**:
the underlying "intbv" value.  Additional methods are included
to extract the integer, fractional, and base intbv.val (see
above).

Neither the *int()* nor the *ord()* are convertible for the
initial enhancement.

    >>> int(fixbv(3.333, min=-8, max=8, res=256)
    3
    >>> ord(fixbv(3.333, min=-8, max=8, res=256)
    853

**  ordinal: the mathematical definition of two related
     finite sets.  I am using (hopefully correctly) that the
     ordinal is mapping of a non-repeating finite-set to an
     enumerated integer set, in this case fixed-point to a
     signed enumerated set.


no mixed arithmetic operations
================================
The fixbv can only be added and subtracted to other fixbv
variables.  Only when *fwl* is 0 does it make sense to add
an (int, long, intbv) but this is the exception.  It only
makes sense to add *fixbv* types.  The fixbv addition and
subtraction will only support adding and subtracting fixbv
types.


I have been slow to complete the implementation, I wanted to
gather all the feedback first.  For the curious, the current
implementation is at [5].  The current implementation is
missing the comparison operator definitions and there is currently
a bug using the fixbv with a Signal (to be addressed soon).

Any questions or input let me know.


[1] http://dev.myhdl.org/meps/mep-111.html
[2] http://www.digitalsignallabs.com/fp.pdf
[3] http://www.vhdl.org/fphdl/Fixed_ug.pdf
[4] http://www.accellera.org/downloads/standards/systemc/accept_license
[5] https://bitbucket.org/cfelton/myhdl_09dev_fixbv