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 68 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 69 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 type_bfp

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 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_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 type_scalar_int

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.

See also

left_shift_t

typedef int left_shift_t#

A leftwards arithmetic bit-shift.

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

See also

right_shift_t

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

Scalar Types (Floating-Point)#

group type_scalar_float
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 type_scalar_fixed

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