XMath Types¶

Each of the main operand types used in this library has a short-hand which is used as a prefix in the naming of API operations. The following tables can be used for reference.

Common Vector Types¶

The following table indicates the types and abbreviations associated with various common vector types.

Table 1 Common Vector Types¶
Prefix	Object Type	Notes
`vect_s32`	`int32_t[]`	Raw vector of signed 32-bit integers.
`vect_s16`	`int16_t[]`	Raw vector of signed 16-bit integers.
`vect_s8`	`int8_t[]`	Raw vector of signed 8-bit integers.
`vect_complex_s32`	`complex_s32_t[]`	Raw vector of complex 32-bit integers.
`vect_complex_s16`	(`int16_t[]`, `int16_t[]`)	Complex 16-bit vectors are usually represented as a pair of 16-bit vectors. This is an optimization due to the word-alignment requirement when loading data into the VPU’s vector registers.
`chunk_s32`	`int32_t[8]`	A ‘chunk’ is a fixed size vector corresponding to the size of the VPU vector registers.
`vect_qXX`	`int32_t[]`	When used in an API function name, the `XX` will be an actual number (e.g. `vect_q30_exp_small()`) indicating the fixed-point interpretation used by that function.
`vect_f32`	`float[]`	Raw vector of standard IEEE `float`
`vect_float_s32`	`float_s32_t[]`	Vector of non-standard 32-bit floating-point scalars.
`bfp_s32`	`bfp_s32_t`	Block floating-point vector contianing 32-bit mantissas.
`bfp_s16`	`bfp_s16_t`	Block floating-point vector contianing 16-bit mantissas.
`bfp_complex_s32`	`bfp_complex_s32_t`	Block floating-point vector contianing complex 32-bit mantissas.
`bfp_complex_s16`	`bfp_complex_s16_t`	Block floating-point vector contianing complex 16-bit mantissas.

Common Scalar Types¶

The following table indicates the types and abbreviations associated with various common scalar types.

Table 2 Common Scalar Types¶
Prefix	Object Type	Notes
`s32`	`int32_t`	32-bit signed integer. May be a simple integer, a fixed-point value or the mantissa of a floating-point value.
`s16`	`int16_t`	16-bit signed integer. May be a simple integer, a fixed-point value or the mantissa of a floating-point value.
`s8`	`int8_t`	8-bit signed integer. May be a simple integer, a fixed-point value or the mantissa of a floating-point value.
`complex_s32`	`complex_s32_t`	Signed complex integer with 32-bit real and 32-bit imaginary parts.
`complex_s16`	`complex_s16_t`	Signed complex integer with 16-bit real and 16-bit imaginary parts.
`float_s64`	`float_s64_t`	Non-standard floating-point scalar with exponent and 64-bit mantissa.
`float_s32`	`float_s32_t`	Non-standard floating-point scalar with exponent and 32-bit mantissa.
`qXX`	`int32_t`	32-bit fixed-point value with `XX` fractional bits (i.e. exponent of `-XX`).
`f32`	`float`	Standard IEEE 754 single-precision `float`.
`f64`	`double`	Standard IEEE 754 double-precision `float`.
`float_complex_s64`	`float_complex_s64_t`	Floating-point value with exponent and complex mantissa with 64-bit real and imaginary parts.
`float_complex_s32`	`float_complex_s32_t`	Floating-point value with exponent and complex mantissa with 32-bit real and imaginary parts.
`float_complex_s16`	`float_complex_s16_t`	Floating-point value with exponent and complex mantissa with 16-bit real and imaginary parts.
N/A	`exponent_t`	Represents an exponent \(p\) as in \(2^p\). Unless otherwise specified exponent are always assumed to have a base of \(2\).
N/A	`headroom_t`	The headroom of a scalar or vector. See Headroom for more information.
N/A	`right_shift_t`	Represents a rightward bit-shift of a certain number of bits. Care should be taken, as sometimes this is treated as unsigned.
N/A	`left_shift_t`	Represents a leftward bit-shift of a certain number of bits. Care should be taken, as sometimes this is treated as unsigned.

Block Floating-Point Types¶

group xmath Block Floating-Point Types

Enums

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 <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.

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 <types.h>

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 <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 <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.

Scalar Types (Integer)¶

group xmath Scalar Types (Integer)

Typedefs

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.

Scalar Types (Floating-Point)¶

group xmath Scalar Types (Floating-point)

struct float_s32_t¶

#include <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 <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 <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 <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 <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

struct complex_float_t¶

#include <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 <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.

Scalar Types (Fixed-Point)¶

group xmath Scalar Types (Fixed-point)

Typedefs

typedef int32_t q1_31¶

Q1.31 (Signed) Fixed-point value.

Represents a signed, 32-bit, real, fixed-point value with 31 fractional bits (i.e. an implicit exponent of \(-31\)).

Capable of representing values in the range \(\left[-1.0, 1.0\right)\)

typedef int32_t q2_30¶

Q2.30 (Signed) Fixed-point value.

Represents a signed, 32-bit, real, fixed-point value with 30 fractional bits (i.e. an implicit exponent of \(-30\)).

Capable of representing values in the range \(\left[-2.0, 2.0\right)\)

typedef int32_t q4_28¶

Q4.28 (Signed) Fixed-point value.

Represents a signed, 32-bit, real, fixed-point value with 28 fractional bits (i.e. an implicit exponent of \(-28\)).

Capable of representing values in the range \(\left[-8.0, 8.0\right)\)

typedef int32_t q8_24¶

Q8.24 (Signed) Fixed-point value.

Represents a signed, 32-bit, real, fixed-point value with 24 fractional bits (i.e. an implicit exponent of \(-24\)).

Capable of representing values in the range \(\left[-128.0, 128.0\right)\)

typedef uint32_t uq0_32¶

UQ0.32 (Unsigned) Fixed-point value.

Represents an unsigned, 32-bit, real, fixed-point value with 32 fractional bits (i.e. an implicit exponent of \(-32\)).

Capable of representing values in the range \(\left[0, 1.0\right)\)

typedef uint32_t uq1_31¶

UQ1.31 (Unsigned) Fixed-point value.

Represents an unsigned, 32-bit, real, fixed-point value with 31 fractional bits (i.e. an implicit exponent of \(-31\)).

Capable of representing values in the range \(\left[0, 2.0\right)\)

typedef uint32_t uq2_30¶

UQ2.30 (Unsigned) Fixed-point value.

Represents an unsigned, 32-bit, real, fixed-point value with 30 fractional bits (i.e. an implicit exponent of \(-30\)).

Capable of representing values in the range \(\left[0, 4.0\right)\)

typedef uint32_t uq4_28¶

UQ4.28 (Unsigned) Fixed-point value.

Represents an unsigned, 32-bit, real, fixed-point value with 28 fractional bits (i.e. an implicit exponent of \(-28\)).

Capable of representing values in the range \(\left[0, 16.0\right)\)

typedef uint32_t uq8_24¶

UQ8.24 (Unsigned) Fixed-point value.

Represents an unsigned, 32-bit, real, fixed-point value with 24 fractional bits (i.e. an implicit exponent of \(-24\)).

Capable of representing values in the range \(\left[0, 256.0\right)\)

typedef q1_31 sbrad_t¶

Specialized angular unit used by this library.

‘sbrad’ is a kind of modified binary radian (hence ‘brad’) which takes into account the symmetries of \(sin(\theta)\).

Use radians_to_sbrads() to convert from radians to sbrad_t.

typedef q8_24 radian_q24_t¶: Angle measurement in radians using a Q8.24 representation.

Misc Types¶

group xmath Misc Types

struct split_acc_s32_t¶

#include <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.