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 floating-point value or block floating-point vector.

For a floating-point 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 floating-point vector.

typedef int right_shift_t¶

A rightwards arithmetic bit-shift.

Represents a right bit-shift to be applied to an integer. May be signed or unsigned, depending on context. If signed, negative values represent leftward bit-shifts.

See also

right_shift_t

typedef int32_t fixed_s32_t¶

A 32-bit fixed-point scalar.

Represents a 32-bit fixed-point scalar with a Q-format implied by the context in which it occurs. Typically this type will be used for fixed-point function parameters as a hint to the user to check the documentation for the required Q-format.

If a function has a fixed_s32_t parameter ending with _qXX (where the X are digits), the XX typically indicates the number of fractional bits. For example, a fixed_s32_t parameter called coef_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 16-bit fixed-point scalar.

Represents a 16-bit fixed-point scalar with a Q-format implied by the context in which it occurs. Typically this type will be used for fixed-point function parameters as a hint to the user to check the documentation for the required Q-format.

If a function has a fixed_s16_t parameter ending with _qXX (where the X are digits), the XX typically indicates the number of fractional bits. For example, a fixed_s16_t parameter called coef_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 64-bit real part and 64-bit imaginary part.

Public Members

int64_t re¶: Real Part.

int64_t im¶: Imaginary Part.

struct complex_s32_t¶

#include <xs3_math_types.h>

A complex number with a 32-bit real part and 32-bit imaginary part.

Public Members

int32_t re¶: Real Part.

int32_t im¶: Imaginary Part.

struct complex_s16_t¶

#include <xs3_math_types.h>

A complex number with a 16-bit real part and 16-bit imaginary part.

Public Members

int16_t re¶: Real Part.

int16_t im¶: Imaginary Part.

struct float_s32_t¶

#include <xs3_math_types.h>

A floating-point scalar with a 32-bit mantissa.

Represents a (non-standard) floating-point value given by \( M \cdot 2^{x} \), where \(M\) is the 32-bit mantissa mant, and \(x\) is the exponent exp.

To convert a float_s32_t to a standard IEEE754 single-precision floating-point value (which may result in a loss of precision):

float to_ieee_float(float_s32_t x) {
    return ldexpf(x.mant, x.exp);
}

Public Members

int32_t mant¶: 32-bit mantissa

exponent_t exp¶: exponent

struct float_s64_t¶

#include <xs3_math_types.h>

A floating-point scalar with a 64-bit mantissa.

Represents a (non-standard) floating-point value given by \( M \cdot 2^{x} \), where \(M\) is the 64-bit mantissa mant, and \(x\) is the exponent exp.

To convert a float_s64_t to a standard IEEE754 double-precision floating-point value (which may result in a loss of precision):

double to_ieee_float(float_s64_t x) {
    return ldexp(x.mant, x.exp);
}

Public Members

int64_t mant¶: 64-bit mantissa

exponent_t exp¶: exponent

struct float_complex_s16_t¶

#include <xs3_math_types.h>

A complex floating-point scalar with a complex 16-bit mantissa.

Represents a (non-standard) complex floating-point value given by \( A + j\cdot B \cdot 2^{x} \), where \(A\) is mant.re, the 16-bit real part of the mantissa, \(B\) is mant.im, the 16-bit imaginary part of the mantissa, and \(x\) is the exponent exp.

Public Members

complex_s16_t mant¶: complex 16-bit mantissa

exponent_t exp¶: exponent

struct float_complex_s32_t¶

#include <xs3_math_types.h>

A complex floating-point scalar with a complex 32-bit mantissa.

Represents a (non-standard) complex floating-point value given by \( A + j\cdot B \cdot 2^{x} \), where \(A\) is mant.re, the 32-bit real part of the mantissa, \(B\) is mant.im, the 32-bit imaginary part of the mantissa, and \(x\) is the exponent exp.

Public Members

complex_s32_t mant¶: complex 32-bit mantissa

exponent_t exp¶: exponent

struct float_complex_s64_t¶

#include <xs3_math_types.h>

A complex floating-point scalar with a complex 64-bit mantissa.

Represents a (non-standard) complex floating-point value given by \( A + j\cdot B \cdot 2^{x} \), where \(A\) is mant.re, the 64-bit real part of the mantissa, \(B\) is mant.im, the 64-bit imaginary part of the mantissa, and \(x\) is the exponent exp.

Public Members

complex_s64_t mant¶: complex 64-bit mantissa

exponent_t exp¶: exponent

Block Floating-Point 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.

struct bfp_s32_t¶

#include <xs3_math_types.h>

A block floating-point vector of 32-bit 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 (non-modular) arithmetic.

The BFP API keeps the hr field up-to-date with the current headroom of data[] 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.

struct bfp_s16_t¶

#include <xs3_math_types.h>

[bfp_s32_t]

A block floating-point vector of 16-bit 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 (non-modular) arithmetic.

The BFP API keeps the hr field up-to-date with the current headroom of data[] 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.

struct bfp_complex_s32_t¶

#include <xs3_math_types.h>

[bfp_s16_t]

A block floating-point vector of complex 32-bit 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 (non-modular) arithmetic, and i is sqrt(-1)

The BFP API keeps the hr field up-to-date with the current headroom of data[] 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.

struct bfp_complex_s16_t¶

#include <xs3_math_types.h>

[bfp_complex_s32_t]

A block floating-point vector of complex 16-bit elements.

Initialized with the bfp_complex_s16_init() function.

The BFP API keeps the hr field up-to-date with the current headroom of data[] 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.

Misc Types¶

struct complex_float_t¶

#include <xs3_math_types.h>

[bfp_complex_s16_t]

A complex number with a single-precision floating-point real part and a single-precision floating-point imaginary part.

Public Members

float re¶: Real Part.

float im¶: Imaginary Part.

struct complex_double_t¶

#include <xs3_math_types.h>

A complex number with a double-precision floating-point real part and a double-precision floating-point imaginary part.

Public Members

double re¶: Real Part.

double im¶: Imaginary Part.

struct xs3_split_acc_s32_t¶

#include <xs3_math_types.h>

Holds a set of sixteen 32-bit accumulators in the XS3 VPU’s internal format.

The XS3 VPU stores 32-bit accumulators with the most significant 16-bits stored in one 256-bit vector register (called vD), and the least significant 16-bit stored in another 256-bit 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 16-bit integer 0xSTUVWXYZ is always exactly 0x0000WXYZ larger than 0xSTUV0000. To combine the upper and lower 16-bits of an accumulator, use (((int32_t)vD[k]) << 16) + vR[k].

Public Members

int16_t vD[16]¶: Most significant 16 bits of accumulators.

uint16_t vR[16]¶: Least significant 16 bits of accumulators.