ISSUE 390

Number 390
Category enhancement
Synopsis 17.11: math functions
State lrmdraft
Class enhancement
Arrival-DateJul 09 2003
Originator sharp@cadence.com
Release 2001b: 17.11
Environment
Description
This is a request from my Verilog-AMS contact.

Verilog-AMS has added a variety of math functions to the
language (ln, log, exp, sqrt, min, max, abs, pow, ceil,
floor, sin, cos, tan, asin, acos, atan, atan2, sinh,
cosh, tanh, asinh, acosh, atanh, hypot). They would
like to have these added to Verilog. Kurt might also
be happy about this.

I do not approve of the way that these were added in
Verilog-AMS. They should have been added as new built-in
system functions, following the normal naming convention
of starting with a dollar sign (e.g. $log). Instead, they
were added as a completely new kind of construct, and
pollute the name space with two dozen new reserved words.
When I asked why this was done, the answer was that they
wanted to be able to use them in constant expressions, and
this was not possible with system functions.

The proper solution is to make these built-in system
functions, and allow the use of certain built-in system
functions in constant expressions. In addition to these
math functions, the conversion functions in 17.8 would
be appropriate for this. All of the others have side
effects or only make sense during execution. I had
already noticed that since $signed and $unsigned were
defined to be system functions, it is not possible to
use them in constant expressions, which is a problem.

This request is related to enhancement/386 and
enhancement/387.
Fix
As revised and passed by BTF 2004-11-29:

In Section 17 introduction, ADD to list of system functions:

Math functions [17.11]

$clog2 $asin
$ln $acos
$log10 $atan
$exp $atan2
$sqrt $hypot
$pow $sinh
$floor $cosh
$ceil $tanh
$sin $asinh
$cos $acosh
$tan $atanh

In Section 17, ADD:

17.11 Math functions

There are integer and real math functions.

17.11.1 Integer math functions

integer result;
result = $clog2(n);

The system function $clog2 returns the ceiling of the log base 2 of the
argument (the log rounded up to an integer value). The argument can be
an integer or an arbitrary sized vector value. The argument is treated
as an unsigned value, and an argument value of 0 will produce a result
of 0.

This system function can be used to compute the minimum address width
necessary to address a memory of a given size, or the minimum vector
width necessary to represent a given number of states. It can be used
in a constant expression, as specified in Clause 4.

17.11.2 Real math functions

---------------------------------------------------
Function C equivalent Description
---------------------------------------------------
$ln(x) log(x) Natural logarithm
$log10(x) log10(x) Decimal logarithm
$exp(x) exp(x) Exponential
$sqrt(x) sqrt(x) Square root
$pow(x,y) pow(x,y) x**y
$floor(x) floor(x) Floor
$ceil(x) ceil(x) Ceiling
$sin(x) sin(x) Sine
$cos(x) cos(x) Cosine
$tan(x) tan(x) Tangent
$asin(x) asin(x) Arc-sine
$acos(x) acos(x) Arc-cosine
$atan(x) atan(x) Arc-tangent
$atan2(x,y) atan2(x,y) Arc-tangent of x/y
$hypot(x,y) hypot(x,y) sqrt(x*x + y*y)
$sinh(x) sinh(x) Hyperbolic sine
$cosh(x) cosh(x) Hyperbolic cosine
$tanh(x) tanh(x) Hyperbolic tangent
$asinh(x) asinh(x) Arc-hyperbolic sine
$acosh(x) acosh(x) Arc-hyperbolic cosine
$atanh(x) atanh(x) Arc-hyperbolic tangent
---------------------------------------------------

These system functions accept real arguments, and return
a real result. Their behavior matches the equivalent C
language standard math library function indicated.
Audit-Trail
From: Steven Sharp <sharp@cadence.com>
To: etf-bugs@boyd.com
Cc:
Subject: enhancement/390: PROPOSAL - add math functions
Date: Wed, 24 Nov 2004 20:08:00 -0500 (EST)

Proposal for adding math and transcendental functions

Commentary:

I checked with our Verilog-AMS team, and they were very much in favor of
adding the math functions from Verilog-AMS as system functions in Verilog.

To be consistent with Verilog, these need to have names starting with $.
However, it is possible to define a Verilog function without a $ in the
name, which calls one of these functions as its implementation. With
Shalom's proposal for 387, such Verilog functions could be used as
constant functions. In SystemVerilog, it would be possible to define
a package of math functions implemented this way. By adding an import
of this package, the existing AMS syntax would work. In Verilog, the
Verilog function definitions would need to be `included instead.

This seems to be a reasonable compromise that is consistent with Verilog,
and allows the existing AMS syntax, without reserving all of these
function names as keywords. When I mentioned this, I was told that
certain of these functions do come up as identifiers in Verilog designs.

Some issues that came up while writing this proposal:

Verilog-AMS uses function names "ln" and "log" where C uses "log" and
"log10", for the natural log and common log (base e and base 10). I
went with the Verilog-AMS names. This could be changed to match C.
Another option would be to go with "ln" and "log10", which doesn't
match either, but doesn't leave any ambiguity about what the base of
"log" is.

Verilog-AMS has abs, min and max functions, but they are very restrictive.
I felt that they needed to be generalized more before being added. There
are a number of issues that would need to be resolved with that, and there
is not enough time to reach consensus. As a result, I decided to leave
them out for now. While they would get more use than most of the other
functions being added, they are also easily replaced with parameterized
macros using the conditional operator. For example, abs(x) can be
implemented with

`define abs(x) (((x) > 0) ? (x) : -(x))

Perhaps they can be added later.

I also added a $clog2 system function. Given the difficulty of correctly
writing the similar Verilog constant function, and that this is by far
the most commonly used constant function, it seemed reasonable to build
it in. It also avoids the need for the user to include the Verilog
function definition in every module where they want to use it.


Actual Proposal:
-----------------------------------------------------

In Section 17 introduction, ADD to list of system functions:

Math functions [17.11]

$ln $log
$exp $sqrt
$pow $floor
$ceil $clog2
$sin $cos
$tan $asin
$acos $atan
$atan2 $hypot
$sinh $cosh
$tanh $asinh
$acosh $atanh

In Section 17, ADD:

17.11 Math functions

There are integer and real math functions.

17.11.1 Integer math functions

integer width;
width = $clog2(size);

The system function $clog2 returns the ceiling of the log base 2 of the
argument (the log rounded up to an integer value). The argument can be
an integer or an arbitrary sized vector value. The argument is treated
as an unsigned value, and an argument value of 0 will produce a result
of 0.

This system function can be used to compute the minimum address width
necessary to address a memory of a given size, or the minimum vector
width necessary to represent a given number of states. It can be used
in a constant expression, as specified in Section 4.

17.11.2 Real math functions

---------------------------------------------------
Function C equivalent Description
---------------------------------------------------
$ln(x) log(x) Natural logarithm
$log(x) log10(x) Decimal logarithm
$exp(x) exp(x) Exponential
$sqrt(x) sqrt(x) Square root
$pow(x,y) pow(x,y) x**y
$floor(x) floor(x) Floor
$ceil(x) ceil(x) Ceiling
$sin(x) sin(x) Sine
$cos(x) cos(x) Cosine
$tan(x) tan(x) Tangent
$asin(x) asin(x) Arc-sine
$acos(x) acos(x) Arc-cosine
$atan(x) atan(x) Arc-tangent
$atan2(x,y) atan2(x,y) Arc-tangent of x/y
$hypot(x,y) hypot(x,y) sqrt(x*x + y*y)
$sinh(x) sinh(x) Hyperbolic sine
$cosh(x) cosh(x) Hyperbolic cosine
$tanh(x) tanh(x) Hyperbolic tangent
$asinh(x) asinh(x) Arc-hyperbolic sine
$acosh(x) acosh(x) Arc-hyperbolic cosine
$atanh(x) atanh(x) Arc-hyperbolic tangent
---------------------------------------------------

These system functions accept real arguments, and return
a real result. Their behavior matches the equivalent C
language standard math library function indicated.

From: Shalom.Bresticker@freescale.com
To: Steven Sharp <sharp@cadence.com>
Cc: btf-bugs@boyd.com
Subject: Re: enhancement/390: PROPOSAL - add math functions
Date: Thu, 25 Nov 2004 11:18:17 +0200 (IST)

Steven,

You should enter the proposal through the Add Proposal function in the
database, in order to change its state to Proposal.

Minor comments:

> Math functions [17.11]
>
> $ln $log
> $exp $sqrt
> $pow $floor
> $ceil $clog2
> $sin $cos
> $tan $asin
> $acos $atan
> $atan2 $hypot
> $sinh $cosh
> $tanh $asinh
> $acosh $atanh

Better orders visually would be:

$clog2 $asin
$log $acos
$ln $atan
$sqrt $atan2
$exp $sinh
$pow $cosh
$floor $tanh
$ceil $asinh
$sin $acosh
$cos $atanh
$tan $hypot

or

$ln $asin
$log $acos
$sqrt $atan
$hypot $atan2
$exp $sinh
$pow $cosh
$floor $tanh
$ceil $asinh
$sin $acosh
$cos $atanh
$tan $clog2

changing the order of description correspondingly in the continuation.

It might be good to emphasize the integer nature of $clog2 in the name by adding an "i".


> In Section 17, ADD:
>
> 17.11 Math functions
>
> There are integer and real math functions.
>
> 17.11.1 Integer math functions
>
> integer width;
> width = $clog2(size);
>
> The system function $clog2 returns the ceiling of the log base 2 of the
> argument (the log rounded up to an integer value). The argument can be
> an integer or an arbitrary sized vector value. The argument is treated
> as an unsigned value, and an argument value of 0 will produce a result
> of 0.
>
> This system function can be used to compute the minimum address width
> necessary to address a memory of a given size, or the minimum vector
> width necessary to represent a given number of states. It can be used
> in a constant expression, as specified in Section 4.

I would prefer not to call the arguments and value "size" and "width"
unless they are shown as an example usage.


> 17.11.2 Real math functions
>
> ---------------------------------------------------
> Function C equivalent Description
> ---------------------------------------------------
> $ln(x) log(x) Natural logarithm
> $log(x) log10(x) Decimal logarithm
> $exp(x) exp(x) Exponential
> $sqrt(x) sqrt(x) Square root
> $pow(x,y) pow(x,y) x**y
> $floor(x) floor(x) Floor
> $ceil(x) ceil(x) Ceiling
> $sin(x) sin(x) Sine
> $cos(x) cos(x) Cosine
> $tan(x) tan(x) Tangent
> $asin(x) asin(x) Arc-sine
> $acos(x) acos(x) Arc-cosine
> $atan(x) atan(x) Arc-tangent
> $atan2(x,y) atan2(x,y) Arc-tangent of x/y
> $hypot(x,y) hypot(x,y) sqrt(x*x + y*y)
> $sinh(x) sinh(x) Hyperbolic sine
> $cosh(x) cosh(x) Hyperbolic cosine
> $tanh(x) tanh(x) Hyperbolic tangent
> $asinh(x) asinh(x) Arc-hyperbolic sine
> $acosh(x) acosh(x) Arc-hyperbolic cosine
> $atanh(x) atanh(x) Arc-hyperbolic tangent
> ---------------------------------------------------
>
> These system functions accept real arguments, and return
> a real result. Their behavior matches the equivalent C
> language standard math library function indicated.

A problem with real $floor and $ceil functions is that the real argument
may be on the edge of an integer value, e.g., 3.9999 or 4.0001.
In such a case, it is possible that $clog2(n) would give a different
value from $ceil($log2(n)).

--
Shalom Bresticker Shalom.Bresticker @freescale.com
Design & Verification Methodology Tel: +972 9 9522268
Freescale Semiconductor Israel, Ltd. Fax: +972 9 9522890
POB 2208, Herzlia 46120, ISRAEL Cell: +972 50 5441478

[ ]Freescale Internal Use Only [ ]Freescale Confidential Proprietary

From: Steven Sharp <sharp@cadence.com>
To: sharp@cadence.com, Shalom.Bresticker@freescale.com
Cc: btf-bugs@boyd.com
Subject: Re: enhancement/390: PROPOSAL - add math functions
Date: Fri, 26 Nov 2004 16:15:54 -0500 (EST)

>Better orders visually would be:
>
>$clog2 $asin ...

You're right. I should have re-ordered them to match the organization
of the sections after I modified that. The original had the transcendental
functions in a separate section.

Steven Sharp
sharp@cadence.com

From: Shalom.Bresticker@freescale.com
To: Steven Sharp <sharp@cadence.com>
Cc: btf-bugs@boyd.com
Subject: Re: enhancement/390: PROPOSAL - add math functions
Date: Sat, 27 Nov 2004 18:35:42 +0200 (IST)

I've thunk about this a litle more.

I don't have the C standard with me, which might fill a few gaps in my
education...

1. I don't understand why floor and ceil return real instead of integer.

2. The current $rtoi is like floor for positive numbers, except that
$rtoi returns an integer. It is not explicit about negative numbers,
but I understand that $rtoi(-123.45) returns -123. I'm not sure what
floor and ceil return.

3. Direct assignment of a real to an integer type does a rounding function,
but it might be convenient to have an explicit rounding function, though
again I would think it should return an integer instead of real.

Shalom


> Maybe a $round function also?

--
Shalom Bresticker Shalom.Bresticker @freescale.com
Design & Verification Methodology Tel: +972 9 9522268
Freescale Semiconductor Israel, Ltd. Fax: +972 9 9522890
POB 2208, Herzlia 46120, ISRAEL Cell: +972 50 5441478

[ ]Freescale Internal Use Only [ ]Freescale Confidential Proprietary

From: Steven Sharp <sharp@cadence.com>
To: sharp@cadence.com, Shalom.Bresticker@freescale.com
Cc: btf-bugs@boyd.com
Subject: Re: enhancement/390: PROPOSAL - add math functions
Date: Sat, 27 Nov 2004 15:15:36 -0500 (EST)

>1. I don't understand why floor and ceil return real instead of integer.

I can speculate. If you need an integer floor or ceil, you can always
just get the real floor or ceil and assign it to an integer. But if
you need a real floor or ceil, you can't necessarily get that by using
an integer floor or ceil, because the value might be too big for an
integer (e.g. 1.0e20).

>2. The current $rtoi is like floor for positive numbers, except that
>$rtoi returns an integer. It is not explicit about negative numbers,
>but I understand that $rtoi(-123.45) returns -123. I'm not sure what
>floor and ceil return.

floor(-123.45) would return -124, because that is the largest integer
less than -123.45. It always goes downward, whereas $rtoi goes toward
zero (i.e. truncates).

>3. Direct assignment of a real to an integer type does a rounding function,
>but it might be convenient to have an explicit rounding function, though
>again I would think it should return an integer instead of real.

I have seen a round() function in a C math library to go with ceil() and
floor(), but it isn't standard. It was defined in terms of the current IEEE
floating point rounding mode, and C doesn't require IEEE floating point, so
that couldn't be standard.


Steven Sharp
sharp@cadence.com

From: Shalom.Bresticker@freescale.com
To: Steven Sharp <sharp@cadence.com>
Cc: btf-bugs@boyd.com
Subject: Re: enhancement/390: PROPOSAL - add math functions
Date: Sun, 28 Nov 2004 06:10:36 +0200 (IST)

Thanks, but how useful are real floor/ceil/round?
If you are already doing real calculations, you probably don't care about
making it into an integer.

Shalom


On Sat, 27 Nov 2004, Steven Sharp wrote:

> >1. I don't understand why floor and ceil return real instead of integer.
>
> I can speculate. If you need an integer floor or ceil, you can always
> just get the real floor or ceil and assign it to an integer. But if
> you need a real floor or ceil, you can't necessarily get that by using
> an integer floor or ceil, because the value might be too big for an
> integer (e.g. 1.0e20).

--
Shalom Bresticker Shalom.Bresticker @freescale.com
Design & Verification Methodology Tel: +972 9 9522268
Freescale Semiconductor Israel, Ltd. Fax: +972 9 9522890
POB 2208, Herzlia 46120, ISRAEL Cell: +972 50 5441478

[ ]Freescale Internal Use Only [ ]Freescale Confidential Proprietary

From: Steven Sharp <sharp@cadence.com>
To: btf@boyd.com, etf-bugs@boyd.com
Cc:
Subject: enhancement/390: PROPOSAL - as amended and passed by BTF
Date: Mon, 29 Nov 2004 17:01:56 -0500 (EST)

Proposal for adding math and transcendental functions

-----------------------------------------------------

In Section 17 introduction, ADD to list of system functions:

Math functions [17.11]

$clog2 $asin
$ln $acos
$log10 $atan
$exp $atan2
$sqrt $hypot
$pow $sinh
$floor $cosh
$ceil $tanh
$sin $asinh
$cos $acosh
$tan $atanh

In Section 17, ADD:

17.11 Math functions

There are integer and real math functions.

17.11.1 Integer math functions

integer result;
result = $clog2(n);

The system function $clog2 returns the ceiling of the log base 2 of the
argument (the log rounded up to an integer value). The argument can be
an integer or an arbitrary sized vector value. The argument is treated
as an unsigned value, and an argument value of 0 will produce a result
of 0.

This system function can be used to compute the minimum address width
necessary to address a memory of a given size, or the minimum vector
width necessary to represent a given number of states. It can be used
in a constant expression, as specified in Clause 4.

17.11.2 Real math functions

---------------------------------------------------
Function C equivalent Description
---------------------------------------------------
$ln(x) log(x) Natural logarithm
$log10(x) log10(x) Decimal logarithm
$exp(x) exp(x) Exponential
$sqrt(x) sqrt(x) Square root
$pow(x,y) pow(x,y) x**y
$floor(x) floor(x) Floor
$ceil(x) ceil(x) Ceiling
$sin(x) sin(x) Sine
$cos(x) cos(x) Cosine
$tan(x) tan(x) Tangent
$asin(x) asin(x) Arc-sine
$acos(x) acos(x) Arc-cosine
$atan(x) atan(x) Arc-tangent
$atan2(x,y) atan2(x,y) Arc-tangent of x/y
$hypot(x,y) hypot(x,y) sqrt(x*x + y*y)
$sinh(x) sinh(x) Hyperbolic sine
$cosh(x) cosh(x) Hyperbolic cosine
$tanh(x) tanh(x) Hyperbolic tangent
$asinh(x) asinh(x) Arc-hyperbolic sine
$acosh(x) acosh(x) Arc-hyperbolic cosine
$atanh(x) atanh(x) Arc-hyperbolic tangent
---------------------------------------------------

These system functions accept real arguments, and return
a real result. Their behavior matches the equivalent C
language standard math library function indicated.


Fix replaced by Shalom.Bresticker@freescale.com on Tue Nov 30 01:12:30 2004

As revised and passed by BTF 2004-11-29:

In Section 17 introduction, ADD to list of system functions:

Math functions [17.11]

$clog2 $asin
$ln $acos
$log10 $atan
$exp $atan2
$sqrt $hypot
$pow $sinh
$floor $cosh
$ceil $tanh
$sin $asinh
$cos $acosh
$tan $atanh

In Section 17, ADD:

17.11 Math functions

There are integer and real math functions.

17.11.1 Integer math functions

integer result;
result = $clog2(n);

The system function $clog2 returns the ceiling of the log base 2 of the
argument (the log rounded up to an integer value). The argument can be
an integer or an arbitrary sized vector value. The argument is treated
as an unsigned value, and an argument value of 0 will produce a result
of 0.

This system function can be used to compute the minimum address width
necessary to address a memory of a given size, or the minimum vector
width necessary to represent a given number of states. It can be used
in a constant expression, as specified in Clause 4.

17.11.2 Real math functions

---------------------------------------------------
Function C equivalent Description
---------------------------------------------------
$ln(x) log(x) Natural logarithm
$log10(x) log10(x) Decimal logarithm
$exp(x) exp(x) Exponential
$sqrt(x) sqrt(x) Square root
$pow(x,y) pow(x,y) x**y
$floor(x) floor(x) Floor
$ceil(x) ceil(x) Ceiling
$sin(x) sin(x) Sine
$cos(x) cos(x) Cosine
$tan(x) tan(x) Tangent
$asin(x) asin(x) Arc-sine
$acos(x) acos(x) Arc-cosine
$atan(x) atan(x) Arc-tangent
$atan2(x,y) atan2(x,y) Arc-tangent of x/y
$hypot(x,y) hypot(x,y) sqrt(x*x + y*y)
$sinh(x) sinh(x) Hyperbolic sine
$cosh(x) cosh(x) Hyperbolic cosine
$tanh(x) tanh(x) Hyperbolic tangent
$asinh(x) asinh(x) Arc-hyperbolic sine
$acosh(x) acosh(x) Arc-hyperbolic cosine
$atanh(x) atanh(x) Arc-hyperbolic tangent
---------------------------------------------------

These system functions accept real arguments, and return
a real result. Their behavior matches the equivalent C
language standard math library function indicated.


Unformatted


Hosted by Boyd Technology