2007/643: New libmvec interfaces
Rod Evans
Rod.Evans at sun.com
Tue Nov 6 09:20:11 PST 2007
I'm sponsoring the following case for Douglas Priest. This case
qualifies for Architectural self-review, but we wish to record
the following information.
-----------------------------------------------------------------------
This project adds the following entry points to libmvec, specifically
both the (SPARC-only) libmvec.a shipped with the compilers and the
(SPARC/x86/x64) libmvec.so.1 in Nevada.
(public entry points)
vsinpi_
vcospi_
vsincospi_
vsinpif_
vcospif_
vsincospif_
(internal entry points, used only by the compiler)
__vsinpi
__vsinpi_
__vcospi
__vcospi_
__vsincospi
__vsincospi_
__vsinpif
__vsinpif_
__vcospif
__vcospif_
__vsincospif
__vsincospif_
These routines provide vector trigonometric functions with the argument
implicitly scaled by pi, e.g., vsinpi_ computes sin(pi*x) for each x
in the argument vector. A draft man page for vsinpi_/vsinpif_ as well
as one for libmvec as a whole appear below. Similar pages for the other
functions in libmvec will be added to Nevada.
References:
LSARC 1997/131 xvector
LSARC 1998/323 libmvec additions
LSARC 2001/774 Vector Square Root Functions
LSARC 2002/564 Vector Reciprocal Hypot Functions
LSARC 2003/737 Shared Vector Math Library libmvec.so.1
-----------------------------------------------------------------------
Vector Math Library Functions vsinpi(3MVEC)
NAME
vsinpi_, vsinpif_ - vector sinpi functions
SYNOPSIS
cc [ flag... ] file... -lmvec [ library... ]
void vsinpi_(int *n, double * restrict x, int *stridex, dou-
ble * restrict y, int *stridey);
void vsinpif_(int *n, float * restrict x, int *stridex,
float * restrict y, int *stridey);
DESCRIPTION
These routines evaluate the sinpi function, defined by
sinpi(x) := sin(pi * x), for an entire vector of values at
once. The first parameter specifies the number of values to
compute. Subsequent parameters specify the argument and re-
sult vectors. Each vector is described by a pointer to the
first element and a stride, which is the increment between
successive elements.
Specifically, vsinpi_(n, x, sx, y, sy) computes y[i * *sy] =
sinpi(x[i * *sx]) for each i = 0, 1, ..., *n - 1. vsinpif_
performs the same computation for single precision data.
USAGE
The element count *n must be greater than zero. The strides
for the argument and result arrays may be arbitrary inte-
gers, but the arrays themselves must not be the same or
overlap. (A zero stride effectively collapses an entire
vector into a single element. A negative stride causes a
vector to be accessed in descending memory order, but note
that the corresponding pointer must still point to the first
element of the vector to be used; if the stride is negative,
this will be the highest-addressed element in memory. This
convention differs from the Level 1 BLAS, in which array
parameters always refer to the lowest-addressed element in
memory even when negative increments are used.)
These functions assume that the default round-to-nearest
rounding direction mode is in effect. On x86, these func-
tions also assume that the default round-to-64-bit rounding
precision mode is in effect. The result of calling a vector
function with a non-default rounding mode in effect is unde-
fined.
These functions handle special cases and exceptions in the
spirit of IEEE 754. In particular,
- sinpi(NaN) is NaN,
- sinpi(+/-0) is ±0,
- sinpi(+/-Inf) is NaN, and an invalid operation exception
is raised.
An application wanting to check for exceptions should call
feclearexcept(FE_ALL_EXCEPT) before calling these functions.
On return, if fetestexcept(FE_INVALID | FE_DIVBYZERO |
FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an exception has
been raised. The application can then examine the result or
argument vectors for exceptional values. Note that some
vector functions may raise the inexact exception even if all
elements of the argument array are such that the numerical
results are exact.
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Committed |
|_____________________________|_____________________________|
| MT-Level | MT-Safe |
|_____________________________|_____________________________|
SEE ALSO
trig_sun(3M), feclearexcept(3M), fetestexcept(3M), attri-
butes(5)
-----------------------------------------------------------------------
Interface Libraries libmvec(3LIB)
NAME
libmvec - vector math library
SYNOPSIS
cc [ flag ... ] file ... -lmvec [ library ... ]
DESCRIPTION
Functions in this library evaluate common elementary mathe-
matical functions for an entire vector of arguments at once.
INTERFACES
The shared object libmvec.so.1 provides the public inter-
faces listed below. See intro(3) for additional information
on shared object interfaces.
vatan_ vatanf_
vatan2_ vatan2f_
vcos_ vcosf_
vcospi_ vcospif_
vexp_ vexpf_
vhypot_ vhypotf_
vlog_ vlogf_
vpow_ vpowf_
vrhypot_ vrhypotf_
vrsqrt_ vrsqrtf_
vsin_ vsinf_
vsincos_ vsincosf_
vsincospi_ vsincospif_
vsinpi_ vsinpif_
vsqrt_ vsqrtf_
vz_abs_ vc_abs_
vz_exp_ vc_exp_
vz_log_ vc_log_
vz_pow_ vc_pow_
FILES
/lib/libmvec.so.1 shared object
/lib/64/libmvec.so.1 64-bit shared object
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | SUNWlibmsr |
|_____________________________|_____________________________|
| MT-Level | MT-Safe |
|_____________________________|_____________________________|
SEE ALSO
complex.h(3HEAD), libm(3LIB), attributes(5)
-----------------------------------------------------------------------
Release Binding: Patch/Micro
All "v*" and "__v*" interfaces: Committed
--
Rod.
More information about the opensolaris-arc
mailing list