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

# 32-bit scalar API

group scalar_s32_api

  Defines

  S32_SQRT_MAX_DEPTH

    Maximum bit-depth to calculate with s32_sqrt().

  Functions

  float s32_to_f32(const int32_t mantissa, const exponent_t exp)

    Pack a floating point value into an IEEE 754 single-precision float.

    The value returned is the nearest representable approximation to \( m \cdot 2^{p} \) where \(m\) is `mantissa` and \(p\) is `exp`.

    Example

          // Pack -12345678 * 2^{-13} into a float
          int32_t mant = -12345678;
          exponent_t exp = -13;
          float val = s32_to_f32(mant, exp);

          printf("%e <-- %ld * 2^(%d)\n", val, mant, exp);

    Note

    This operation may result in a loss of precision.

    Parameters:

      - mantissa – [in] Mantissa of value to be packed

      - exp – [in] Exponent of value to be packed

    Returns:

      `float` representation of input value

  int16_t s32_to_s16(exponent_t *a_exp, const int32_t b, const exponent_t b_exp)

    Convert a 32-bit floating-point scalar to a 16-bit floating-point scalar.

    Converts a 32-bit floating-point scalar, represented by the 32-bit mantissa `b` and exponent `b_exp`, into a 16-bit floating-point scalar, represented by the 16-bit returned mantissa and output exponent `a_exp`.

    Parameters:

      - a_exp – [out] Output exponent

      - b – [in] 32-bit input mantissa

      - b_exp – [in] Input exponent

    Returns:

      16-bit output mantissa

  int32_t s32_sqrt(exponent_t *a_exp, const int32_t b, const exponent_t b_exp, const unsigned depth)

    Compute the square root of a 32-bit floating-point scalar.

    `b` and `b_exp` together represent the input \(b \cdot 2^{b\_exp}\) . Likewise, `a` and `a_exp` together represent the result \(a \cdot 2^{a\_exp}\) .

    `depth` indicates the number of MSb’s which will be calculated. Smaller values here will execute more quickly at the cost of reduced precision. The maximum valid value for `depth` is S32_SQRT_MAX_DEPTH.

    Operation Performed

      \[\begin{aligned} a \cdot 2^{a\_exp} \leftarrow \sqrt{\left( b \cdot 2^{b\_exp} \right)} \end{aligned}\]
    Parameters:

      - a_exp – [out] Output exponent \(a\_exp\)

      - b – [in] Input mantissa \(b\)

      - b_exp – [in] Input exponent \(b\_exp\)

      - depth – [in] Number of most significant bits to calculate

    Returns:

      Output mantissa \(a\)

  int32_t s32_inverse(exponent_t *a_exp, const int32_t b)

    Compute the inverse of a 32-bit integer.

    `b` represents the integer \(b\) . `a` and `a_exp` together represent the result \(a \cdot 2^{a\_exp}\) .

    Operation Performed

      \[\begin{aligned} a \cdot 2^{a\_exp} \leftarrow \frac{1}{b} \end{aligned}\]

    If \(b\) is the mantissa of a fixed- or floating-point value with an implicit or explicit exponent \(b\_exp\) , then

    Fixed- or Floating-point

    \( \begin{aligned} \frac{1}{b \cdot 2^{b\_exp}} &= \frac{1}{b} \cdot 2^{-b\_exp} \\ &= a \cdot 2^{a\_exp} \cdot 2^{-b\_exp} \\ &= a \cdot 2^{a\_exp - b\_exp} \end{aligned} \)

    and so \(b\_exp\) should be subtracted from the output exponent \(a\_exp\) .

    Parameters:

      - a_exp – [out] Output exponent \(a\_exp\)

      - b – [in] Input integer \(b\)

    Returns:

      Output mantissa \(a\)

  int32_t s32_mul(exponent_t *a_exp, const int32_t b, const int32_t c, const exponent_t b_exp, const exponent_t c_exp)

    Compute the product of two 32-bit floating-point scalars.

    `a` and `a_exp` together represent the result \(a \cdot 2^{a\_exp}\) .

    `b` and `b_exp` together represent the result \(b \cdot 2^{b\_exp}\) .

    `c` and `c_exp` together represent the result \(c \cdot 2^{c\_exp}\) .

    Operation Performed

      \[\begin{aligned} a \cdot 2^{a\_exp} \leftarrow \left( b\cdot 2^{b\_exp} \right) \cdot \left( c\cdot 2^{c\_exp} \right) \end{aligned}\]
    Parameters:

      - a_exp – [out] Output exponent \(a\_exp\)

      - b – [in] First input mantissa \(b\)

      - c – [in] Second input mantissa \(c\)

      - b_exp – [in] First input exponent \(b\_exp\)

      - c_exp – [in] Second input exponent \(c\_exp\)

    Returns:

      Output mantissa \(a\)

  sbrad_t radians_to_sbrads(const radian_q24_t theta)

    Convert angle from radians to a modified binary representation.

    Some trig functions, such as sbrad_sin(), rather than taking an angle specified in radians (e.g. radian_q24_t), require their argument to be a modified representation of the angle, as an sbrad_t. The modified binary representation takes into account various properies of the \(sin(\theta)\) function to simplify certain operations.

    For any angle \(\theta\) there is a unique angle \(\alpha\) where \(-1\le\alpha\le1\) and \(sin(\frac{\pi}{2}\alpha) = sin(\theta)\) . This function essentially just maps the input angle \(\theta\) onto the corresponding angle \(\alpha\) in that region and returns the result in a Q1.31 format.

    In this library, the unit of the resulting angle \(\alpha\) is referred to as an ‘sbrad’. ‘brad’ because \(\alpha\) is a kind of binary angular measurement, and ‘s’ because the symmetries of \(sin(\theta)\) are what’s being accounted for.

    Parameters:

      - theta – [in] Input angle \(\theta\) , in radians (Q8.24)

    Returns:

      Output angle \(\alpha\) , in sbrads

  q2_30 sbrad_sin(const sbrad_t theta)

    Compute the sine of the specified angle.

    This function computes \(sin(\frac{\pi}{2}\theta)\) , returning the result in Q2.30 format.

    The input angle \(\theta\) must be expressed in sbrads (sbrad_t), and must represent a value between \(\pm 0.5\) (inclusive) (as a Q1.31).

    Operation Performed

      \[\begin{aligned} & sin(\frac{\pi}{2}\theta) \end{aligned}\]
    Parameters:

      - theta – [in] Input angle \(\theta\) , in sbrads (see radians_to_sbrads)

    Returns:

      Sine of the specified angle in Q2.30 format.

  q2_30 sbrad_tan(const sbrad_t theta)

    Compute the tangent of the specified angle.

    This function computes \(tan(\frac{\pi}{2}\theta)\) , returning the result in Q2.30 format.

    The input angle \(\theta\) must be expressed in sbrads (sbrad_t), and must represent a value between \(\pm 0.25\) (inclusive) (as a Q1.31).

    Operation Performed

      \[\begin{aligned} & tan(\frac{\pi}{2}\theta) \end{aligned}\]
    Parameters:

      - theta – [in] Input angle \(\theta\) , in sbrads (see radians_to_sbrads)

    Returns:

      Tangent of the specified angle in Q2.30 format.

  q2_30 q24_sin(const radian_q24_t theta)

    Compute the sine of the specified angle.

    This function computes \(sin(\theta)\) , returning the result in Q2.30 format.

    Operation Performed

      \[\begin{aligned} & sin(\theta) \end{aligned}\]
    Parameters:

      - theta – [in] Input angle \(\theta\) , in radians (Q8.24)

    Returns:

      \(sin(\theta)\) as a Q2.30

  q2_30 q24_cos(const radian_q24_t theta)

    Compute the cosine of the specified angle.

    This function computes \(cos(\theta)\) , returning the result in Q2.30 format.

    Operation Performed

      \[\begin{aligned} & cos(\theta) \end{aligned}\]
    Parameters:

      - theta – [in] Input angle \(\theta\) , in radians (Q8.24)

    Returns:

      \(cos(\theta)\) as a Q2.30

  float_s32_t q24_tan(const radian_q24_t theta)

    Compute the tangent of the specified angle.

    This function computes \(tan(\theta)\) . The result is returned as a float_s32_t containing a mantissa and exponent.

    The value of \(tan(\theta)\) is considered undefined where \(theta=\frac{\pi}{2}+k\pi\) for any integer \(k\) . An exception will be raised if \(\theta\) meets this condition.

    Operation Performed

      \[\begin{aligned} & tan(\theta) \end{aligned}\]
    Parameters:

      - theta – [in] Input angle \(\theta\) , in radians (Q8.24)

    Throws ET_ARITHMETIC:

      Raised if \(tan(\theta)\) is undefined.

    Returns:

      \(tan(\theta)\) as a float_s32_t

  q2_30 q30_exp_small(const q2_30 x)

    Compute \(e^x\) for Q2.30 value near \(0\) .

    This function computes \(e^x\) where \(x\) is a fixed-point value with 30 fractional bits.

    This function implements \(e^x\) using a truncated power series, and is only intended to be used for inputs in the range \(-0.5 \le x \le 0.5\) .

    The output is also in the Q2.30 format.

    For the range \(-0.5 \le x \le 0.5\) , the maximum observed error (compared to `exp(double)` from `math.h`) was `2` (which corresponds to \(2^{-29}\) ).

    For the range \(-1.0 \le x \le 1.0\) , the corresponding maximum observed error was `324`, or approximately \(2^{-21}\) .

    To compute \(e^x\) for \(x\) outside of \(\left[-0.5, 0.5\right]\) , use `float_s32_exp()`.

    Operation Performed

      \[\begin{aligned} & y \leftarrow e^x \end{aligned}\]
    Parameters:

      - x – [in] Input value \(x\)

    Returns:

      \(y\)

  q8_24 q24_logistic(const q8_24 x)

    Evaluate the logistic function at the specified point.

    This function computes the value of the logistic function \(y =\frac{1}{1+e^{-x}}\) . This is a sigmoidal curve bounded below by \(y = 0\) and above by \(y = 1\) .

    The input \(x\) and output \(y\) are both Q8.24 fixed-point values.

    If speed is greatly preferred to precision, `q24_logistic_fast()` can be used instead.

    Operation Performed

      \[\begin{aligned} & y \leftarrow \frac{1}{1+e^{-x}} \end{aligned}\]
    Parameters:

      - x – [in] Input value \(x\)

    Returns:

      \(y\)

  q8_24 q24_logistic_fast(const q8_24 x)

    Evaluate the logistic function at the specified point.

    This function computes the value of the logistic function \(y =\frac{1}{1+e^{-x}}\) . This is a sigmoidal curve bounded below by \(y = 0\) and above by \(y = 1\) .

    The input \(x\) and output \(y\) are both Q8.24 fixed-point values.

    This implementation trades off precision for speed, approximating results in a piece-wise linear manner. If a precise result is desired, `q24_logistic()` should be used instead.

    Operation Performed

      \[\begin{aligned} & y \leftarrow \frac{1}{1+e^{-x}} \end{aligned}\]
    Parameters:

      - x – [in] Input value \(x\)

    Returns:

      \(y\)

  void s32_to_chunk_s32(int32_t a[VPU_INT32_EPV], int32_t b)

    Broadcast an integer to a vector chunk.

    This function broadcasts the input \(b\) to the 8 elements of \(\bar a\) .

    Operation Performed

      \[\begin{aligned} & a_k \leftarrow b \end{aligned}\]
    Parameters:

      - a – [out] Output chunk \(\bar a\)

      - b – [in] Input value \(b\)

    Throws ET_LOAD_STORE:

      Raised if `a` is not double word-aligned (See Note: Vector Alignment)

  void q30_powers(q2_30 a[], const q2_30 b, const unsigned N)

    Get the first \(N\) powers of \(b\).

    This function computes the first \(N\) powers (starting with \(0\) ) of the Q2.30 input \(b\) . The results are output as \(\bar a\) , also in Q2.30 format.

    Operation Performed

      \[\begin{split}\begin{aligned} & a_0 \leftarrow 2^{30} = \mathtt{Q30(1.0)} \\ & a_k \leftarrow round\left(\frac{a_{k-1}\cdot b}{2^{30}}\right) \\ & \qquad\text{for }k \in {0..N-1} \end{aligned}\end{split}\]
    Parameters:

      - a – [out] Output \(\bar a\)

      - b – [in] Input \(b\)

      - N – [in] Number of elements of \(\bar a\) to compute

  void s32_odd_powers(int32_t a[], const int32_t b, const unsigned count, const right_shift_t shr)

    Fill vector with odd powers of \(b\) .

    This function populates the elements of output vector \(\bar a\) with the odd powers of input \(b\) . The first `count` odd powers of \(b\) are output. The highest power output will be \(2\cdot\mathtt{count}-1\) .

    The 64-bit product of each multiplication is right-shifted by `shr` bits and truncated to the 32 least significant bits. If \(b\) is a fixed-point value with `shr` fractional bits, then each \(a_k\) will have the same Q-format as input \(b\) . `shr` must be non-negative.

    This function neither rounds nor saturates results. It is up to the user to ensure overflows are avoided.

    Typical use-case is computing a power series of a function with odd symmetry.

    Operation Performed

      \[\begin{split}\begin{aligned} & b_{sqr} = \frac{b^2}{2^{\mathtt{shr}}} \\ & a_0 \leftarrow b \\ & a_k \leftarrow \frac{a_{k-1},b_{sqr}}{\mathtt{shr}} \\ & \qquad\text{for } k \in {1, 2, 3, ..., \mathtt{count} - 1} \end{aligned}\end{split}\]
    Parameters:

      - a – [out] Output vector \(\bar a\)

      - b – [in] Input \(b\)

      - count – [in] Number of elements to output.

      - shr – [in] Number of bits to right-shift 64-bit products.