XS3 Math Types¶
Scalar Types¶

typedef int exponent_t¶
An exponent.
Many places in this API make use of integers representing the exponent associated with some floatingpoint value or block floatingpoint vector.
For a floatingpoint value \(x \cdot 2^p\), \(p\) is the exponent, and may usually be positive or negative.

typedef unsigned headroom_t¶
Headroom of some integer or integer array.
Represents the headroom of a signed or unsigned integer, complex integer or channel pair, or the headroom of the mantissa array of a block floatingpoint vector.

typedef int right_shift_t¶
A rightwards arithmetic bitshift.
Represents a right bitshift to be applied to an integer. May be signed or unsigned, depending on context. If signed, negative values represent leftward bitshifts.
See also

typedef int left_shift_t¶
A leftwards arithmetic bitshift.
Represents a left bitshift to be applied to an integer. May be signed or unsigned, depending on context. If signed, negative values represent rightward bitshifts.
See also

typedef int32_t fixed_s32_t¶
A 32bit fixedpoint scalar.
Represents a 32bit fixedpoint scalar with a Qformat implied by the context in which it occurs. Typically this type will be used for fixedpoint function parameters as a hint to the user to check the documentation for the required Qformat.
If a function has a
fixed_s32_t
parameter ending with_qXX
(where theX
are digits), theXX
typically indicates the number of fractional bits. For example, afixed_s32_t
parameter calledcoef_q30
would imply 30 fractional bits and an associated exponent of 30. This is just a convention, however, and this interpretation should be verified in the function’s documentation.

typedef int16_t fixed_s16_t¶
A 16bit fixedpoint scalar.
Represents a 16bit fixedpoint scalar with a Qformat implied by the context in which it occurs. Typically this type will be used for fixedpoint function parameters as a hint to the user to check the documentation for the required Qformat.
If a function has a
fixed_s16_t
parameter ending with_qXX
(where theX
are digits), theXX
typically indicates the number of fractional bits. For example, afixed_s16_t
parameter calledcoef_q14
would imply 14 fractional bits and an associated exponent of 14. This is just a convention, however, and this interpretation should be verified in the function’s documentation.

struct complex_s64_t¶
 #include <xs3_math_types.h>
A complex number with a 64bit real part and 64bit imaginary part.

struct complex_s32_t¶
 #include <xs3_math_types.h>
A complex number with a 32bit real part and 32bit imaginary part.

struct complex_s16_t¶
 #include <xs3_math_types.h>
A complex number with a 16bit real part and 16bit imaginary part.

struct float_s32_t¶
 #include <xs3_math_types.h>
A floatingpoint scalar with a 32bit mantissa.
Represents a (nonstandard) floatingpoint value given by \( M \cdot 2^{x} \), where \(M\) is the 32bit mantissa
mant
, and \(x\) is the exponentexp
.To convert a
float_s32_t
to a standard IEEE754 singleprecision floatingpoint value (which may result in a loss of precision):float to_ieee_float(float_s32_t x) { return ldexpf(x.mant, x.exp); }

struct float_s64_t¶
 #include <xs3_math_types.h>
A floatingpoint scalar with a 64bit mantissa.
Represents a (nonstandard) floatingpoint value given by \( M \cdot 2^{x} \), where \(M\) is the 64bit mantissa
mant
, and \(x\) is the exponentexp
.To convert a
float_s64_t
to a standard IEEE754 doubleprecision floatingpoint value (which may result in a loss of precision):double to_ieee_float(float_s64_t x) { return ldexp(x.mant, x.exp); }

struct float_complex_s16_t¶
 #include <xs3_math_types.h>
A complex floatingpoint scalar with a complex 16bit mantissa.
Represents a (nonstandard) complex floatingpoint value given by \( A + j\cdot B \cdot 2^{x} \), where \(A\) is
mant.re
, the 16bit real part of the mantissa, \(B\) ismant.im
, the 16bit imaginary part of the mantissa, and \(x\) is the exponentexp
.

struct float_complex_s32_t¶
 #include <xs3_math_types.h>
A complex floatingpoint scalar with a complex 32bit mantissa.
Represents a (nonstandard) complex floatingpoint value given by \( A + j\cdot B \cdot 2^{x} \), where \(A\) is
mant.re
, the 32bit real part of the mantissa, \(B\) ismant.im
, the 32bit imaginary part of the mantissa, and \(x\) is the exponentexp
.

struct float_complex_s64_t¶
 #include <xs3_math_types.h>
A complex floatingpoint scalar with a complex 64bit mantissa.
Represents a (nonstandard) complex floatingpoint value given by \( A + j\cdot B \cdot 2^{x} \), where \(A\) is
mant.re
, the 64bit real part of the mantissa, \(B\) ismant.im
, the 64bit imaginary part of the mantissa, and \(x\) is the exponentexp
.
Block FloatingPoint Types¶

enum bfp_flags_e¶
(Opaque) Flags field for BFP vectors.
Warning
Users should not manually modify fields of this type, as it is intended to be opaque.
Values:

enumerator BFP_FLAG_DYNAMIC¶
Indicates that BFP vector’s mantissa buffer(s) were allocated dynamically
This flag lets the bfp_*_dealloc() functions know whether the mantissa vector must be free()ed.

enumerator BFP_FLAG_DYNAMIC¶

struct bfp_s32_t¶
 #include <xs3_math_types.h>
A block floatingpoint vector of 32bit elements.
Initialized with the
bfp_s32_init()
function.The logical quantity represented by each element of this vector is:
data[i]*2^(exp)
where the multiplication and exponentiation are using real (nonmodular) arithmetic.The BFP API keeps the
hr
field uptodate with the current headroom ofdata[]
so as to minimize precision loss as elements become small. [bfp_s32_t]Public Members

int32_t *data¶
Pointer to the underlying element buffer.

exponent_t exp¶
Exponent associated with the vector.

headroom_t hr¶
Current headroom in the
data[]

unsigned length¶
Current size of
data[]
, expressed in elements

bfp_flags_e flags¶
BFP vector flags. Users should not normally modify these manually.

int32_t *data¶

struct bfp_s16_t¶
 #include <xs3_math_types.h>
A block floatingpoint vector of 16bit elements.
Initialized with the
bfp_s16_init()
function.The logical quantity represented by each element of this vector is:
data[i] * 2^(exp)
where the multiplication and exponentiation are using real (nonmodular) arithmetic.The BFP API keeps the
hr
field uptodate with the current headroom ofdata[]
so as to minimize precision loss as elements become small. [bfp_s16_t]Public Members

int16_t *data¶
Pointer to the underlying element buffer.

exponent_t exp¶
Exponent associated with the vector.

headroom_t hr¶
Current headroom in the
data[]

unsigned length¶
Current size of
data[]
, expressed in elements

bfp_flags_e flags¶
BFP vector flags. Users should not normally modify these manually.

int16_t *data¶

struct bfp_complex_s32_t¶
 #include <xs3_math_types.h>
A block floatingpoint vector of complex 32bit elements.
Initialized with the
bfp_complex_s32_init()
function.The logical quantity represented by each element of this vector is:
data[k].re * 2^(exp) + i * data[k].im * 2^(exp)
where the multiplication and exponentiation are using real (nonmodular) arithmetic, and i is sqrt(1)The BFP API keeps the
hr
field uptodate with the current headroom ofdata[]
so as to minimize precision loss as elements become small. [bfp_complex_s32_t]Public Members

complex_s32_t *data¶
Pointer to the underlying element buffer.

exponent_t exp¶
Exponent associated with the vector.

headroom_t hr¶
Current headroom in the
data[]

unsigned length¶
Current size of
data[]
, expressed in elements

bfp_flags_e flags¶
BFP vector flags. Users should not normally modify these manually.

complex_s32_t *data¶

struct bfp_complex_s16_t¶
 #include <xs3_math_types.h>
A block floatingpoint vector of complex 16bit elements.
Initialized with the
bfp_complex_s16_init()
function.The logical quantity represented by each element of this vector is:
data[k].re * 2^(exp) + i * data[k].im * 2^(exp)
where the multiplication and exponentiation are using real (nonmodular) arithmetic, and i is sqrt(1)The BFP API keeps the
hr
field uptodate with the current headroom ofdata[]
so as to minimize precision loss as elements become small. [bfp_complex_s16_t]Public Members

int16_t *real¶
Pointer to the underlying element buffer.

int16_t *imag¶
Pointer to the underlying element buffer.

exponent_t exp¶
Exponent associated with the vector.

headroom_t hr¶
Current headroom in the
data[]

unsigned length¶
Current size of
data[]
, expressed in elements

bfp_flags_e flags¶
BFP vector flags. Users should not normally modify these manually.

int16_t *real¶
Misc Types¶

struct complex_float_t¶
 #include <xs3_math_types.h>
A complex number with a singleprecision floatingpoint real part and a singleprecision floatingpoint imaginary part.

struct complex_double_t¶
 #include <xs3_math_types.h>
A complex number with a doubleprecision floatingpoint real part and a doubleprecision floatingpoint imaginary part.

struct xs3_split_acc_s32_t¶
 #include <xs3_math_types.h>
Holds a set of sixteen 32bit accumulators in the XS3 VPU’s internal format.
The XS3 VPU stores 32bit accumulators with the most significant 16bits stored in one 256bit vector register (called vD), and the least significant 16bit stored in another 256bit register (called vR). This struct reflects that internal format, and is occasionally used to store intermediate results.
Note
vR
is unsigned. This reflects the fact that a signed 16bit integer0xSTUVWXYZ
is always exactly0x0000WXYZ
larger than0xSTUV0000
. To combine the upper and lower 16bits of an accumulator, use(((int32_t)vD[k]) << 16) + vR[k]
.