32Bit Complex Vector Prepare Functions#
 group vect_complex_s32_prepare_api
Defines

vect_complex_s32_add_prepare#
Obtain the output exponent and shifts required for a call to
vect_complex_s32_add()
.The logic for computing the shifts and exponents of
vect_complex_s32_add()
is identical to that forvect_s32_add()
.This macro is provided as a convenience to developers and to make the code more coherent.
See also

vect_complex_s32_add_scalar_prepare#
Obtain the output exponent and shifts required for a call to
vect_complex_s32_add_scalar()
.The logic for computing the shifts and exponents of
vect_complex_s32_add_scalar()
is identical to that forvect_s32_add()
.This macro is provided as a convenience to developers and to make the code more readable.
See also

vect_complex_s32_conj_mul_prepare#
Obtain the output exponent and shifts required for a call to
vect_complex_s32_conj_mul()
.The logic for computing the shifts and exponents of
vect_complex_s32_conj_mul()
is identical to that forvect_complex_s32_mul()
.This macro is provided as a convenience to developers and to make the code more readable.
See also

vect_complex_s32_nmacc_prepare#
Obtain the output exponent and shifts required for a call to vect_complex_s32_nmacc().
The logic for computing the shifts and exponents of
vect_complex_s32_nmacc()
is identical to that forvect_complex_s32_macc_prepare()
.This macro is provided as a convenience to developers and to make the code more readable.

vect_complex_s32_conj_macc_prepare#
Obtain the output exponent and shifts required for a call to vect_complex_s32_conj_macc().
The logic for computing the shifts and exponents of
vect_complex_s32_conj_macc()
is identical to that forvect_complex_s32_macc_prepare()
.This macro is provided as a convenience to developers and to make the code more readable.

vect_complex_s32_conj_nmacc_prepare#
Obtain the output exponent and shifts required for a call to vect_complex_s32_conj_nmacc().
The logic for computing the shifts and exponents of
vect_complex_s32_conj_nmacc()
is identical to that forvect_complex_s32_macc_prepare()
.This macro is provided as a convenience to developers and to make the code more readable.

vect_complex_s32_real_scale_prepare#
Obtain the output exponent and shifts required for a call to
vect_complex_s32_real_scale()
.The logic for computing the shifts and exponents of
vect_complex_s32_real_scale()
is identical to that forvect_s32_mul()
.This macro is provided as a convenience to developers and to make the code more readable.
See also

vect_complex_s32_sub_prepare#
Obtain the output exponent and shifts required for a call to
vect_complex_s32_sub()
.The logic for computing the shifts and exponents of
vect_complex_s32_sub()
is identical to that forvect_s32_add()
.This macro is provided as a convenience to developers and to make the code more readable.
See also
Functions

void vect_complex_s32_macc_prepare(exponent_t *new_acc_exp, right_shift_t *acc_shr, right_shift_t *b_shr, right_shift_t *c_shr, const exponent_t acc_exp, const exponent_t b_exp, const exponent_t c_exp, const exponent_t acc_hr, const headroom_t b_hr, const headroom_t c_hr)#
Obtain the output exponent and shifts needed by vect_complex_s32_macc().
This function is used in conjunction with vect_complex_s32_macc() to perform an elementwise multiplyaccumlate of 32bit BFP vectors.
This function computes
new_acc_exp
,acc_shr
,b_shr
andc_shr
, which are selected to maximize precision in the resulting accumulator vector without causing saturation of final or intermediate values. Normally the caller will pass these outputs to their corresponding inputs of vect_complex_s32_macc().acc_exp
is the exponent associated with the accumulator mantissa vector \(\bar a\) prior to the operation, whereasnew_acc_exp
is the exponent corresponding to the updated accumulator vector.b_exp
andc_exp
are the exponents associated with the complex input mantissa vectors \(\bar b\) and \(\bar c\) respectively.acc_hr
,b_hr
andc_hr
are the headrooms of \(\bar a\), \(\bar b\) and \(\bar c\) respectively. If the headroom of any of these vectors is unknown, it can be obtained by calling vect_complex_s32_headroom(). Alternatively, the value0
can always be safely used (but may result in reduced precision). Adjusting Output Exponents

If a specific output exponent
desired_exp
is needed for the result (e.g. for emulating fixedpoint arithmetic), theacc_shr
andbc_sat
produced by this function can be adjusted according to the following:// Presumed to be set somewhere exponent_t acc_exp, b_exp, c_exp; headroom_t acc_hr, b_hr, c_hr; exponent_t desired_exp; ... // Call prepare right_shift_t acc_shr, b_shr, c_shr; vect_complex_s32_macc_prepare(&acc_exp, &acc_shr, &b_shr, &c_shr, acc_exp, b_exp, c_exp, acc_hr, b_hr, c_hr); // Modify results right_shift_t mant_shr = desired_exp  acc_exp; acc_exp += mant_shr; acc_shr += mant_shr; b_shr += mant_shr; c_shr += mant_shr; // acc_shr, b_shr and c_shr may now be used in a call to vect_complex_s32_macc()
When applying the above adjustment, the following conditions should be maintained:
acc_shr > acc_hr
(Shifting any further left may cause saturation)b_shr => b_hr
(Shifting any further left may cause saturation)c_shr => c_hr
(Shifting any further left may cause saturation)
It is up to the user to ensure any such modification does not result in saturation or unacceptable loss of precision.
See also
 Parameters:
new_acc_exp – [out] Exponent associated with output mantissa vector \(\bar a\) (after macc)
acc_shr – [out] Signed arithmetic rightshift used for \(\bar a\) in vect_complex_s32_macc()
b_shr – [out] Signed arithmetic rightshift used for \(\bar b\) in vect_complex_s32_macc()
c_shr – [out] Signed arithmetic rightshift used for \(\bar c\) in vect_complex_s32_macc()
acc_exp – [in] Exponent associated with input mantissa vector \(\bar a\) (before macc)
b_exp – [in] Exponent associated with input mantissa vector \(\bar b\)
c_exp – [in] Exponent associated with input mantissa vector \(\bar c\)
acc_hr – [in] Headroom of input mantissa vector \(\bar a\) (before macc)
b_hr – [in] Headroom of input mantissa vector \(\bar b\)
c_hr – [in] Headroom of input mantissa vector \(\bar c\)

void vect_complex_s32_mag_prepare(exponent_t *a_exp, right_shift_t *b_shr, const exponent_t b_exp, const headroom_t b_hr)#
Obtain the output exponent and input shift used by vect_complex_s32_mag() and vect_complex_s16_mag().
This function is used in conjunction with vect_complex_s32_mag() to compute the magnitude of each element of a complex 32bit BFP vector.
This function computes
a_exp
andb_shr
.a_exp
is the exponent associated with mantissa vector \(\bar a\), and is be chosen to maximize precision when elements of \(\bar a\) are computed. Thea_exp
chosen by this function is derived from the exponent and headroom associated with the input vector.b_shr
is the shift parameter required by vect_complex_s32_mag() to achieve the chosen output exponenta_exp
.b_exp
is the exponent associated with the input mantissa vector \(\bar b\).b_hr
is the headroom of \(\bar b\). If the headroom of \(\bar b\) is unknown it can be calculated using vect_complex_s32_headroom(). Alternatively, the value0
can always be safely used (but may result in reduced precision). Adjusting Output Exponents

If a specific output exponent
desired_exp
is needed for the result (e.g. for emulating fixedpoint arithmetic), theb_shr
produced by this function can be adjusted according to the following:exponent_t desired_exp = ...; // Value known a priori right_shift_t new_b_shr = b_shr + (desired_exp  a_exp);
When applying the above adjustment, the following condition should be maintained:
b_hr + b_shr >= 0
Using larger values than strictly necessary for
b_shr
may result in unnecessary underflows or loss of precision.
See also
 Parameters:
a_exp – [out] Output exponent associated with output mantissa vector \(\bar a\)
b_shr – [out] Signed arithmetic rightshift for \(\bar b\) used by vect_complex_s32_mag()
b_exp – [in] Exponent associated with input mantissa vector \(\bar b\)
b_hr – [in] Headroom of input mantissa vector \(\bar b\)

void vect_complex_s32_mul_prepare(exponent_t *a_exp, right_shift_t *b_shr, right_shift_t *c_shr, const exponent_t b_exp, const exponent_t c_exp, const headroom_t b_hr, const headroom_t c_hr)#
Obtain the output exponent and input shifts used by vect_complex_s32_mul() and vect_complex_s32_conj_mul().
This function is used in conjunction with vect_complex_s32_mul() to perform a complex elementwise multiplication of two complex 32bit BFP vectors.
This function computes
a_exp
,b_shr
andc_shr
.a_exp
is the exponent associated with mantissa vector \(\bar a\), and must be chosen to be large enough to avoid overflow when elements of \(\bar a\) are computed. To maximize precision, this function choosesa_exp
to be the smallest exponent known to avoid saturation (see exception below). Thea_exp
chosen by this function is derived from the exponents and headrooms of associated with the input vectors.b_shr
andc_shr
are the shift parameters required by vect_complex_s32_mul() to achieve the chosen output exponenta_exp
.b_exp
andc_exp
are the exponents associated with the input mantissa vectors \(\bar b\) and \(\bar c\) respectively.b_hr
andc_hr
are the headroom of \(\bar b\) and \(\bar c\) respectively. If the headroom of \(\bar b\) or \(\bar c\) is unknown, they can be obtained by calling vect_complex_s32_headroom(). Alternatively, the value0
can always be safely used (but may result in reduced precision). Adjusting Output Exponents

If a specific output exponent
desired_exp
is needed for the result (e.g. for emulating fixedpoint arithmetic), theb_shr
andc_shr
produced by this function can be adjusted according to the following:exponent_t desired_exp = ...; // Value known a priori right_shift_t new_b_shr = b_shr + (desired_exp  a_exp); right_shift_t new_c_shr = c_shr + (desired_exp  a_exp);
When applying the above adjustment, the following conditions should be maintained:
b_hr + b_shr >= 0
c_hr + c_shr >= 0
Be aware that using smaller values than strictly necessary for
b_shr
andc_shr
can result in saturation, and using larger values may result in unnecessary underflows or loss of precision.
 Notes

Using the outputs of this function, an output mantissa which would otherwise be
INT32_MIN
will instead saturate toINT32_MAX
. This is due to the symmetric saturation logic employed by the VPU and is a hardware feature. This is a corner case which is usually unlikely and results in 1 LSb of error when it occurs.
 Parameters:
a_exp – [out] Exponent associated with output mantissa vector \(\bar a\)
b_shr – [out] Signed arithmetic rightshift for \(\bar b\) used by vect_complex_s32_mul()
c_shr – [out] Signed arithmetic rightshift for \(\bar c\) used by vect_complex_s32_mul()
b_exp – [in] Exponent associated with input mantissa vector \(\bar b\)
c_exp – [in] Exponent associated with input mantissa vector \(\bar c\)
b_hr – [in] Headroom of input mantissa vector \(\bar b\)
c_hr – [in] Headroom of input mantissa vector \(\bar c\)

void vect_complex_s32_real_mul_prepare(exponent_t *a_exp, right_shift_t *b_shr, right_shift_t *c_shr, const exponent_t b_exp, const exponent_t c_exp, const headroom_t b_hr, const headroom_t c_hr)#
Obtain the output exponent and input shifts used by vect_complex_s32_real_mul().
This function is used in conjunction with vect_complex_s32_real_mul() to perform a the elementwise multiplication of complex 32bit BFP vector by a real 32bit BFP vector.
This function computes
a_exp
,b_shr
andc_shr
.a_exp
is the exponent associated with mantissa vector \(\bar a\), and must be chosen to be large enough to avoid overflow when elements of \(\bar a\) are computed. To maximize precision, this function choosesa_exp
to be the smallest exponent known to avoid saturation (see exception below). Thea_exp
chosen by this function is derived from the exponents and headrooms of associated with the input vectors.b_shr
andc_shr
are the shift parameters required by vect_complex_s32_mul() to achieve the chosen output exponenta_exp
.b_exp
andc_exp
are the exponents associated with the input mantissa vectors \(\bar b\) and \(\bar c\) respectively.b_hr
andc_hr
are the headroom of \(\bar b\) and \(\bar c\) respectively. If the headroom of \(\bar b\) or \(\bar c\) is unknown, they can be obtained by calling vect_complex_s32_headroom(). Alternatively, the value0
can always be safely used (but may result in reduced precision). Adjusting Output Exponents

If a specific output exponent
desired_exp
is needed for the result (e.g. for emulating fixedpoint arithmetic), theb_shr
andc_shr
produced by this function can be adjusted according to the following:exponent_t desired_exp = ...; // Value known a priori right_shift_t new_b_shr = b_shr + (desired_exp  a_exp); right_shift_t new_c_shr = c_shr + (desired_exp  a_exp);
When applying the above adjustment, the following conditions should be maintained:
b_hr + b_shr >= 0
c_hr + c_shr >= 0
Be aware that using smaller values than strictly necessary for
b_shr
andc_shr
can result in saturation, and using larger values may result in unnecessary underflows or loss of precision.
 Notes

Using the outputs of this function, an output mantissa which would otherwise be
INT32_MIN
will instead saturate toINT32_MAX
. This is due to the symmetric saturation logic employed by the VPU and is a hardware feature. This is a corner case which is usually unlikely and results in 1 LSb of error when it occurs.
See also
 Parameters:
a_exp – [out] Output exponent associated with \(\bar a\)
b_shr – [out] Signed arithmetic rightshift for \(\bar b\) used by vect_complex_s32_real_mul()
c_shr – [out] Signed arithmetic rightshift for \(\bar c\) used by vect_complex_s32_real_mul()
b_exp – [in] Exponent associated with \(\bar b\)
c_exp – [in] Exponent associated with \(\bar c\)
b_hr – [in] Headroom of mantissa vector \(\bar b\)
c_hr – [in] Headroom of mantissa vector \(\bar c\)

void vect_complex_s32_scale_prepare(exponent_t *a_exp, right_shift_t *b_shr, right_shift_t *c_shr, const exponent_t b_exp, const exponent_t c_exp, const headroom_t b_hr, const headroom_t c_hr)#
Obtain the output exponent and input shifts used by vect_complex_s32_scale().
This function is used in conjunction with vect_complex_s32_scale() to perform a complex multiplication of a complex 32bit BFP vector by a complex 32bit scalar.
This function computes
a_exp
,b_shr
andc_shr
.a_exp
is the exponent associated with mantissa vector \(\bar a\), and must be chosen to be large enough to avoid overflow when elements of \(\bar a\) are computed. To maximize precision, this function choosesa_exp
to be the smallest exponent known to avoid saturation (see exception below). Thea_exp
chosen by this function is derived from the exponents and headrooms associated with the input vectors.b_shr
andc_shr
are the shift parameters required by vect_complex_s32_mul() to achieve the chosen output exponenta_exp
.b_exp
andc_exp
are the exponents associated with the input mantissa vectors \(\bar b\) and \(\bar c\) respectively.b_hr
andc_hr
are the headroom of \(\bar b\) and \(\bar c\) respectively. If the headroom of \(\bar b\) or \(\bar c\) is unknown, they can be obtained by calling vect_complex_s32_headroom(). Alternatively, the value0
can always be safely used (but may result in reduced precision). Adjusting Output Exponents

If a specific output exponent
desired_exp
is needed for the result (e.g. for emulating fixedpoint arithmetic), theb_shr
andc_shr
produced by this function can be adjusted according to the following:exponent_t desired_exp = ...; // Value known a priori right_shift_t new_b_shr = b_shr + (desired_exp  a_exp); right_shift_t new_c_shr = c_shr + (desired_exp  a_exp);
When applying the above adjustment, the following conditions should be maintained:
b_hr + b_shr >= 0
c_hr + c_shr >= 0
Be aware that using smaller values than strictly necessary for
b_shr
andc_shr
can result in saturation, and using larger values may result in unnecessary underflows or loss of precision.
 Notes

Using the outputs of this function, an output mantissa which would otherwise be
INT32_MIN
will instead saturate toINT32_MAX
. This is due to the symmetric saturation logic employed by the VPU and is a hardware feature. This is a corner case which is usually unlikely and results in 1 LSb of error when it occurs.
See also
 Parameters:
a_exp – [out] Exponent associated with output mantissa vector \(\bar a\)
b_shr – [out] Signed arithmetic rightshift for \(\bar b\) used by vect_complex_s32_scale()
c_shr – [out] Signed arithmetic rightshift for \(\bar c\) used by vect_complex_s32_scale()
b_exp – [in] Exponent associated with input mantissa vector \(\bar b\)
c_exp – [in] Exponent associated with input mantissa vector \(\bar c\)
b_hr – [in] Headroom of input mantissa vector \(\bar b\)
c_hr – [in] Headroom of input mantissa vector \(\bar c\)

void vect_complex_s32_squared_mag_prepare(exponent_t *a_exp, right_shift_t *b_shr, const exponent_t b_exp, const headroom_t b_hr)#
Obtain the output exponent and input shift used by vect_complex_s32_squared_mag().
This function is used in conjunction with vect_complex_s32_squared_mag() to compute the squared magnitude of each element of a complex 32bit BFP vector.
This function computes
a_exp
andb_shr
.a_exp
is the exponent associated with mantissa vector \(\bar a\), and is be chosen to maximize precision when elements of \(\bar a\) are computed. Thea_exp
chosen by this function is derived from the exponent and headroom associated with the input vector.b_shr
is the shift parameter required by vect_complex_s32_mag() to achieve the chosen output exponenta_exp
.b_exp
is the exponent associated with the input mantissa vector \(\bar b\).b_hr
is the headroom of \(\bar b\). If the headroom of \(\bar b\) is unknown it can be calculated using vect_complex_s32_headroom(). Alternatively, the value0
can always be safely used (but may result in reduced precision). Adjusting Output Exponents

If a specific output exponent
desired_exp
is needed for the result (e.g. for emulating fixedpoint arithmetic), theb_shr
produced by this function can be adjusted according to the following:exponent_t desired_exp = ...; // Value known a priori right_shift_t new_b_shr = b_shr + (desired_exp  a_exp);
When applying the above adjustment, the following condition should be maintained:
b_hr + b_shr >= 0
Using larger values than strictly necessary for
b_shr
may result in unnecessary underflows or loss of precision.
See also
 Parameters:
a_exp – [out] Output exponent associated with output mantissa vector \(\bar a\)
b_shr – [out] Signed arithmetic rightshift for \(\bar b\) used by vect_complex_s32_squared_mag()
b_exp – [in] Exponent associated with input mantissa vector \(\bar b\)
b_hr – [in] Headroom of input mantissa vector \(\bar b\)

void vect_complex_s32_sum_prepare(exponent_t *a_exp, right_shift_t *b_shr, const exponent_t b_exp, const headroom_t b_hr, const unsigned length)#
Obtain the output exponent and input shift used by vect_complex_s32_sum().
This function is used in conjunction with vect_complex_s32_sum() to compute the sum of elements of a complex 32bit BFP vector.
This function computes
a_exp
andb_shr
.a_exp
is the exponent associated with the 64bit mantissa \(a\) returned by vect_complex_s32_sum(), and must be chosen to be large enough to avoid saturation when \(a\) is computed. To maximize precision, this function choosesa_exp
to be the smallest exponent known to avoid saturation (see exception below). Thea_exp
chosen by this function is derived from the exponents and headrooms associated with the input vector.b_shr
is the shift parameter required by vect_complex_s32_sum() to achieve the chosen output exponenta_exp
.b_exp
is the exponent associated with the input mantissa vector \(\bar b\).b_hr
is the headroom of \(\bar b\). If the headroom of \(\bar b\) is unknown it can be calculated using vect_complex_s32_headroom(). Alternatively, the value0
can always be safely used (but may result in reduced precision).length
is the number of elements in the input mantissa vector \(\bar b\). Adjusting Output Exponents

If a specific output exponent
desired_exp
is needed for the result (e.g. for emulating fixedpoint arithmetic), theb_shr
produced by this function can be adjusted according to the following:exponent_t desired_exp = ...; // Value known a priori right_shift_t new_b_shr = b_shr + (desired_exp  a_exp);
When applying the above adjustment, the following conditions should be maintained:
b_hr + b_shr >= 0
Be aware that using smaller values than strictly necessary for
b_shr
can result in saturation, and using larger values may result in unnecessary underflows or loss of precision.
See also
 Parameters:
a_exp – [out] Exponent associated with output mantissa \(a\)
b_shr – [out] Signed arithmetic rightshift for \(\bar b\) used by vect_complex_s32_sum()
b_exp – [in] Exponent associated with input mantissa vector \(\bar b\)
b_hr – [in] Headroom of input mantissa vector \(\bar b\)
length – [in] Number of elements in \(\bar b\)

vect_complex_s32_add_prepare#