Hide navigation sidebar
Hide table of contents sidebar
Back to top
Toggle table of contents sidebar

# 16-Bit vomplex vector prepare functions

group vect_complex_s16_prepare_api

  Defines

  vect_complex_s16_add_prepare

    Obtain the output exponent and shifts required for a call to `vect_complex_s16_add()`.

    The logic for computing the shifts and exponents of `vect_complex_s16_add()` is identical to that for `vect_s32_add()`.

    This macro is provided as a convenience to developers and to make the code more readable.

    See also

    vect_s32_add_prepare()

  vect_complex_s16_add_scalar_prepare

    Obtain the output exponent and shifts required for a call to `vect_complex_s16_add_scalar()`.

    The logic for computing the shifts and exponents of `vect_complex_s16_add_scalar()` is identical to that for `vect_s32_add()`.

    This macro is provided as a convenience to developers and to make the code more readable.

    See also

    vect_s16_add_prepare()

  vect_complex_s16_conj_mul_prepare

    Obtain the output exponent and shifts required for a call to `vect_complex_s16_conj_mul()`.

    The logic for computing the shifts and exponents of `vect_complex_s16_conj_mul()` is identical to that for `vect_complex_s16_mul()`.

    This macro is provided as a convenience to developers and to make the code more readable.

    See also

    vect_complex_s16_mul_prepare()

  vect_complex_s16_nmacc_prepare

    Obtain the output exponent and shifts required for a call to vect_complex_s16_nmacc().

    The logic for computing the shifts and exponents of `vect_complex_s16_nmacc()` is identical to that for `vect_complex_s16_macc()`.

    This macro is provided as a convenience to developers and to make the code more readable.

    See also

    vect_complex_s16_macc_prepare(), vect_complex_s16_nmacc()

  vect_complex_s16_conj_macc_prepare

    Obtain the output exponent and shifts required for a call to vect_complex_s16_conj_macc().

    The logic for computing the shifts and exponents of `vect_complex_s16_conj_macc()` is identical to that for `vect_complex_s16_macc()`.

    This macro is provided as a convenience to developers and to make the code more readable.

    See also

    vect_complex_s16_macc_prepare(), vect_complex_s16_conj_macc()

  vect_complex_s16_conj_nmacc_prepare

    Obtain the output exponent and shifts required for a call to vect_complex_s16_conj_nmacc().

    The logic for computing the shifts and exponents of `vect_complex_s16_conj_nmacc()` is identical to that for `vect_complex_s16_macc()`.

    This macro is provided as a convenience to developers and to make the code more readable.

    See also

    vect_complex_s16_macc_prepare(), vect_complex_s16_conj_nmacc()

  vect_complex_s16_mag_prepare

    Obtain the output exponent and shifts required for a call to `vect_complex_s16_mag()`.

    The logic for computing the shifts and exponents of `vect_complex_s16_mag()` is identical to that for `vect_complex_s32_mag()`.

    This macro is provided as a convenience to developers and to make the code more readable.

    See also

    vect_complex_s32_mag_prepare()

  vect_complex_s16_real_scale_prepare

    Obtain the output exponent and shifts required for a call to vect_complex_s16_real_scale().

    The logic for computing the shifts and exponents of `vect_complex_s16_real_scale()` is identical to that for `vect_s32_scale()`.

    This macro is provided as a convenience to developers and to make the code more readable.

    See also

    vect_s16_scale_prepare()

  vect_complex_s16_scale_prepare

    Obtain the output exponent and shifts required for a call to `vect_complex_s16_scale()`.

    The logic for computing the shifts and exponents of `vect_complex_s16_scale()` is identical to that for `vect_complex_s32_mul()`.

    This macro is provided as a convenience to developers and to make the code more readable.

    See also

    vect_complex_s16_mul_prepare()

  vect_complex_s16_sub_prepare

    Obtain the output exponent and shifts required for a call to `vect_complex_s16_sub()`.

    The logic for computing the shifts and exponents of `vect_complex_s16_sub()` is identical to that for `vect_s32_add()`.

    This macro is provided as a convenience to developers and to make the code more readable.

    See also

    vect_s32_add_prepare()

  Functions

  void vect_complex_s16_macc_prepare(exponent_t *new_acc_exp, right_shift_t *acc_shr, right_shift_t *bc_sat, const exponent_t acc_exp, const exponent_t b_exp, const exponent_t c_exp, const headroom_t acc_hr, const headroom_t b_hr, const headroom_t c_hr)

    Obtain the output exponent and shifts needed by vect_complex_s16_macc().

    This function is used in conjunction with vect_complex_s16_macc() to perform an element-wise multiply-accumlate of complex 16-bit BFP vectors.

    This function computes `new_acc_exp` and `acc_shr` and `bc_sat`, 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_s16_macc().

    `acc_exp` is the exponent associated with the accumulator mantissa vector \(\bar a\) prior to the operation, whereas `new_acc_exp` is the exponent corresponding to the updated accumulator vector.

    `b_exp` and `c_exp` are the exponents associated with the complex input mantissa vectors \(\bar b\) and \(\bar c\) respectively.

    `acc_hr`, `b_hr` and `c_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_s16_headroom(). Alternatively, the value `0` 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 fixed-point arithmetic), the `acc_shr` and `bc_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, bc_sat;
          vect_complex_s16_macc_prepare(&acc_exp, &acc_shr, &bc_sat,
                                            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;
          bc_sat  += mant_shr;

          // acc_shr and bc_sat may now be used in a call to vect_complex_s16_macc()

      When applying the above adjustment, the following conditions should be maintained:

      - `bc_sat >= 0` (`bc_sat` is an unsigned right-shift)

      - `acc_shr > -acc_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

    vect_complex_s16_macc

    Parameters:

      - new_acc_exp – [out] Exponent associated with output mantissa vector \(\bar a\) (after macc)

      - acc_shr – [out] Signed arithmetic right-shift used for \(\bar a\) in vect_complex_s16_macc()

      - bc_sat – [out] Unsigned arithmetic right-shift applied to the product of elements \(b_k\) and \(c_k\) in vect_complex_s16_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_s16_mul_prepare(exponent_t *a_exp, right_shift_t *a_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 output shift used by vect_complex_s16_mul() and vect_complex_s16_conj_mul().

    This function is used in conjunction with vect_complex_s16_mul() to perform a complex element-wise multiplication of two complex 16-bit BFP vectors.

    This function computes `a_exp` and `a_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 chooses `a_exp` to be the smallest exponent known to avoid saturation (see exception below). The `a_exp` chosen by this function is derived from the exponents and headrooms of associated with the input vectors.

    `a_shr` is the shift parameter required by vect_complex_s16_mul() to achieve the chosen output exponent `a_exp`.

    `b_exp` and `c_exp` are the exponents associated with the input mantissa vectors \(\bar b\) and \(\bar c\) respectively.

    `b_hr` and `c_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_s16_headroom(). Alternatively, the value `0` 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 fixed-point arithmetic), the `a_shr` and `c_shr` produced by this function can be adjusted according to the following:

          exponent_t desired_exp = ...; // Value known a priori
          right_shift_t new_a_shr = a_shr + (desired_exp - a_exp);

      When applying the above adjustment, the following conditions should be maintained:

      - `new_a_shr >= 0`

      Be aware that using smaller values than strictly necessary for `a_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 `INT16_MIN` will instead saturate to `-INT16_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

    vect_complex_s16_conj_mul, vect_complex_s16_mul

    Parameters:

      - a_exp – [out] Exponent associated with output mantissa vector \(\bar a\)

      - a_shr – [out] Unsigned arithmetic right-shift for \(\bar b\) used by vect_complex_s16_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_s16_real_mul_prepare(exponent_t *a_exp, right_shift_t *a_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 output shift used by vect_complex_s16_real_mul().

    This function is used in conjunction with vect_complex_s16_real_mul() to perform a complex element-wise multiplication of a complex 16-bit BFP vector by a real 16-bit vector.

    This function computes `a_exp` and `a_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 chooses `a_exp` to be the smallest exponent known to avoid saturation (see exception below). The `a_exp` chosen by this function is derived from the exponents and headrooms of associated with the input vectors.

    `a_shr` is the shift parameter required by vect_complex_s16_real_mul() to achieve the chosen output exponent `a_exp`.

    `b_exp` and `c_exp` are the exponents associated with the input mantissa vectors \(\bar b\) and \(\bar c\) respectively.

    `b_hr` and `c_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_s16_headroom(). Alternatively, the value `0` 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 fixed-point arithmetic), the `a_shr` and `c_shr` produced by this function can be adjusted according to the following:

          exponent_t desired_exp = ...; // Value known a priori
          right_shift_t new_a_shr = a_shr + (desired_exp - a_exp);

      When applying the above adjustment, the following conditions should be maintained:

      - `new_a_shr >= 0`

      Be aware that using smaller values than strictly necessary for `a_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 `INT16_MIN` will instead saturate to `-INT16_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

    vect_complex_s16_real_mul

    Parameters:

      - a_exp – [out] Exponent associated with output mantissa vector \(\bar a\)

      - a_shr – [out] Unsigned arithmetic right-shift for \(\bar a\) used by vect_complex_s16_real_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_s16_squared_mag_prepare(exponent_t *a_exp, right_shift_t *a_shr, const exponent_t b_exp, const headroom_t b_hr)

    Obtain the output exponent and input shift used by vect_complex_s16_squared_mag().

    This function is used in conjunction with vect_complex_s16_squared_mag() to compute the squared magnitude of each element of a complex 16-bit BFP vector.

    This function computes `a_exp` and `a_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. The `a_exp` chosen by this function is derived from the exponent and headroom associated with the input vector.

    `a_shr` is the shift parameter required by vect_complex_s16_mag() to achieve the chosen output exponent `a_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_s16_headroom(). Alternatively, the value `0` 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 fixed-point arithmetic), the `a_shr` produced by this function can be adjusted according to the following:

          exponent_t a_exp;
          right_shift_t a_shr;
          vect_s16_mul_prepare(&a_exp, &a_shr, b_exp, c_exp, b_hr, c_hr);
          exponent_t desired_exp = ...; // Value known a priori
          a_shr = a_shr + (desired_exp - a_exp);
          a_exp = desired_exp;

      When applying the above adjustment, the following condition should be maintained:

      - `a_shr >= 0`

      Using larger values than strictly necessary for `a_shr` may result in unnecessary underflows or loss of precision.

    See also

    vect_complex_s16_squared_mag()

    Parameters:

      - a_exp – [out] Output exponent associated with output mantissa vector \(\bar a\)

      - a_shr – [out] Unsigned arithmetic right-shift for \(\bar a\) used by vect_complex_s16_squared_mag()

      - b_exp – [in] Exponent associated with input mantissa vector \(\bar b\)

      - b_hr – [in] Headroom of input mantissa vector \(\bar b\)