32-bit Scalar API

#define S32_SQRT_MAX_DEPTH (31)

用于计算s32_sqrt()的最大位深度。

---

float s32_to_f32()

将浮点值打包成IEEE 754单精度浮点数。

返回的值是最接近于 $m \cdot 2^{p}$ 的可表示近似值，其中 $m$ 是mantissa，$p$ 是exp。

**注意：**这个操作可能会导致精度损失。

示例：

// 将 -12345678 * 2^{-13} 打包成浮点数
int32_t mant = -12345678;
exponent_t exp = -13;
float val = s32_to_f32(mant, exp);

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

参数：

• const int32_t mantissa – [out] 要打包的值的尾数
• const exponent_t exp – [out] 要打包的值的指数

返回值： 输入值的float表示

---

int16_t s32_to_s16()

将32位浮点标量转换为16位浮点标量。

将由32位尾数b和指数b_exp表示的32位浮点标量转换为由返回的16位尾数和输出指数a_exp表示的16位浮点标量。

参数：

• exponent_t* a_exp – [out] 输出指数
• const int32_t b – [out] 32位输入尾数
• const exponent_t b_exp – [out] 输入指数

返回值： 16位输出尾数

---

int32_t s32_sqrt()

计算32位浮点标量的平方根。

b和b_exp一起表示输入 $b \cdot 2^{b\_exp}$。同样，a和a_exp一起表示结果 $a \cdot 2^{a\_exp}$。

depth表示将计算的最高有效位数。这里使用较小的值可以提高执行速度，但会降低精度。depth的最大有效值为@ref S32_SQRT_MAX_DEPTH。

操作： $a \cdot 2^{a\_exp} \leftarrow \sqrt{\left( b \cdot 2^{b\_exp} \right)}$

参数：

• exponent_t* a_exp – [out] 输出指数 $a\_exp$
• const int32_t b – [out] 输入尾数 $b$
• const exponent_t b_exp – [out] 输入指数 $b\_exp$
• const unsigned depth – [out] 要计算的最高有效位数

返回值： 输出尾数 $a$

---

int32_t s32_inverse()

计算32位整数的倒数。

b表示整数 $b$。a和a_exp一起表示结果 $a \cdot 2^{a\_exp}$。

操作： $a \cdot 2^{a\_exp} \leftarrow \frac{1}{b}$

定点或浮点：

如果 $b$ 是具有隐式或显式指数 $b\_exp$ 的定点或浮点值的尾数，则

$\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}$

因此，应该从输出指数 $a\_exp$ 中减去 $b\_exp$。

参数：

• exponent_t* a_exp – [out] 输出指数 $a\_exp$
• const int32_t b – [out] 输入整数 $b$

返回值： 输出尾数 $a$

---

int32_t s32_mul()

计算两个32位浮点标量的乘积。

a和a_exp一起表示结果 $a \cdot 2^{a\_exp}$。

b和b_exp一起表示结果 $b \cdot 2^{b\_exp}$。

c和c_exp一起表示结果 $c \cdot 2^{c\_exp}$。

操作： $a \cdot 2^{a\_exp} \leftarrow \left( b\cdot 2^{b\_exp} \right) \cdot \left( c\cdot 2^{c\_exp} \right)$

参数：

• exponent_t* a_exp – [out] 输出指数 $a\_exp$
• const int32_t b – [out] 第一个输入尾数 $b$
• const int32_t c – [out] 第二个输入尾数 $c$
• const exponent_t b_exp – [out] 第一个输入指数 $b\_exp$
• const exponent_t c_exp – [out] 第二个输入指数 $c\_exp$

返回值： 输出尾数 $a$

---

sbrad_t radians_to_sbrads()

将角度从弧度转换为一种修改的二进制表示。

某些三角函数（例如sbrad_sin()）需要其参数以修改的角度表示，而不是以弧度（例如radian_q24_t）指定的角度。修改的二进制表示考虑了$sin(\theta)$函数的各种属性，以简化某些操作。

对于任何角度 $\theta$，存在唯一的角度 $\alpha$，其中 $-1\le\alpha\le1$ 且 $sin(\frac{\pi}{2}\alpha) = sin(\theta)$。这个函数实际上只是将输入角度 $\theta$ 映射到该区域中的相应角度 $\alpha$，并以Q1.31格式返回结果。

在这个库中，结果角度 $\alpha$ 的单位被称为'sbrad'。'brad'是因为 $\alpha$ 是一种二进制角度测量，'s'是因为考虑到了 $sin(\theta)$ 的对称性。

参数：

• const radian_q24_t theta – [out] 输入角度 $\theta$，以弧度表示（Q8.24）

返回值： 输出角度 $\alpha$，以sbrads表示

---

q2_30 sbrad_sin()

计算指定角度的正弦值。

该函数计算 $sin(\frac{\pi}{2}\theta)$，并以Q2.30格式返回结果。

输入角度 $\theta$ 必须用sbrads表示（参见radians_to_sbrads），并且必须表示为介于$\pm 0.5$（包括边界）之间的值（作为Q1.31）。

操作：

$$sin(\frac{\pi}{2}\theta)$$

参数：

• const sbrad_t theta – [in] 输入角度 $\theta$，以sbrads表示

返回值：

以Q2.30格式表示的指定角度的正弦值。

---

q2_30 sbrad_tan()

计算指定角度的正切值。

该函数计算 $tan(\frac{\pi}{2}\theta)$，并以Q2.30格式返回结果。

输入角度 $\theta$ 必须用sbrads表示（参见radians_to_sbrads），并且必须表示为介于$\pm 0.25$（包括边界）之间的值（作为Q1.31）。

操作：

$$tan(\frac{\pi}{2}\theta)$$

参数：

• const sbrad_t theta – [in] 输入角度 $\theta$，以sbrads表示

返回值：

以Q2.30格式表示的指定角度的正切值。

---

q2_30 q24_sin()

计算指定角度的正弦值。

该函数计算 $sin(\theta)$，并以Q2.30格式返回结果。

操作：

$$sin(\theta)$$

参数：

• const radian_q24_t theta – [in] 输入角度 $\theta$，以弧度表示（Q8.24）

返回值：

以Q2.30格式表示的 $sin(\theta)$。

---

q2_30 q24_cos()

计算指定角度的余弦值。

该函数计算 $cos(\theta)$，并以Q2.30格式返回结果。

操作：

$$cos(\theta)$$

参数：

• const radian_q24_t theta – [in] 输入角度 $\theta$，以弧度表示（Q8.24）

返回值：

以Q2.30格式表示的 $cos(\theta)$。

---

float_s32_t q24_tan()

计算指定角度的正切值。

该函数计算 $tan(\theta)$。结果以float_s32_t形式返回，其中包含尾数和指数。

当 $\theta=\frac{\pi}{2}+k\pi$（其中$k$为整数）时，$tan(\theta)$ 的值被视为未定义。如果 $\theta$ 满足这个条件，将引发异常。

操作：

$$tan(\theta)$$

参数：

• const radian_q24_t theta – [in] 输入角度 $\theta$，以弧度表示（Q8.24）

返回值：

以float_s32_t形式表示的 $tan(\theta)$。

异常：

• ET_ARITHMETIC 如果 $tan(\theta)$ 未定义，将引发异常。

---

q2_30 q30_exp_small()

计算接近 $0$ 的Q2.30值的指数函数 $e^x$。

该函数计算 $e^x$，其中 $x$ 是带有30个小数位的定点值。

该函数使用截断幂级数实现 $e^x$，仅适用于范围在 $-0.5 \le x \le 0.5$ 内的输入。

输出也以Q2.30格式表示。

对于范围 $-0.5 \le x \le 0.5$，与math.h中的exp(double)相比，最大观测误差为 2（对应于 $2^{-29}$）。

对于范围 $-1.0 \le x \le 1.0$，相应的最大观测误差为 324，或者近似为 $2^{-21}$。

要计算 $x$ 超出 $\left[-0.5, 0.5\right]$ 范围的 $e^x$，请使用 float_s32_exp()。

操作：

$$y \leftarrow e^x$$

参数：

• const q2_30 x – [in] 输入值 $x$

返回值：

$y$

---

q8_24 q24_logistic()

计算指定点的逻辑函数值。

该函数计算逻辑函数的值 $y =\frac{1}{1+e^{-x}}$。这是一个在 $y = 0$ 下方和 $y = 1$ 上方有界的S形曲线。

输入 $x$ 和输出 $y$ 都是Q8.24定点值。

如果更注重速度而不是精度，则可以使用 q24_logistic_fast()。

操作：

$$y \leftarrow \frac{1}{1+e^{-x}}$$

参数：

• const q8_24 x – [in] 输入值 $x$

返回值：

$y$

---

q8_24 q24_logistic_fast()

简介： 在指定点处计算逻辑函数的值。

该函数计算逻辑函数 $y =\frac{1}{1+e^{-x}}$ 的值。逻辑函数是一条由 $y = 0$ 和 $y = 1$ 两边界限定的 S 形曲线。

输入 $x$ 和输出 $y$ 都是 Q8.24 定点数。

这个实现在精度和速度之间进行权衡，以分段线性的方式近似结果。如果需要精确的结果，应该使用 q24_logistic()。

操作：

$y \leftarrow \frac{1}{1+e^{-x}}$

参数：

• const q8_24 x – [out] 输入值 $x$

返回值： $y$

---

void s32_to_chunk_s32()

简介： 将整数广播到向量块。

该函数将输入 $b$ 广播到向量块 $\bar{a}$ 的 8 个元素中。

操作：

$a_k \leftarrow b$

参数：

• int32_t a[VPU_INT32_EPV] – [out] 输出向量块 $\bar{a}$
• int32_t b – [out] 输入值 $b$

异常： 如果 a 不是双字对齐的，则引发 ET_LOAD_STORE 异常（参见 @ref note_vector_alignment）

---

void q30_powers()

简介： 获取 $b$ 的前 $N$ 个幂次

该函数计算 Q2.30 输入 $b$ 的前 $N$ 个幂次（从 $0$ 开始）。结果以 Q2.30 格式输出，保存在 $\bar{a}$ 中。

操作：

$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{对于 }k \in \{0..N-1\}$

参数：

• q2_30 a[] – [out] 输出 $\bar{a}$
• const q2_30 b – [out] 输入 $b$
• const unsigned N – [out] 要计算的 $\bar{a}$ 的元素个数

---

void s32_odd_powers()

简介： 用 $b$ 的奇次幂填充向量。

该函数使用输入 $b$ 的奇次幂填充输出向量 $\bar{a}$ 的元素。输出前 count 个奇次幂。最高幂次输出为 $2\cdot\mathtt{count}-1$。

每次乘法的 64 位乘积右移 shr 位，并截断为最低的 32 位。如果 $b$ 是一个带有 shr 位小数的定点数，则每个 $a_k$ 的 Q 格式与输入 $b$ 相同。shr 必须是非负数。

该函数不进行舍入或饱和处理。用户需要确保避免溢出。

典型的用例是计算具有奇对称性函数的幂级数。

操作：

$$\begin{align*} b_{sqr} & = \frac{b^2}{2^{\text{{shr}}}} \\ a_0 & \leftarrow b \\ a_k & \leftarrow \frac{a_{k-1}\,b_{sqr}}{\text{{shr}}} \\ &\text{{对于 }} k \in \{1, 2, 3, ..., \text{{count}} - 1\} \end{align*}$$

参数：

• int32_t a[] – [out] 输出向量 $\bar{a}$
• const int32_t b – [out] 输入 $b$
• const unsigned count – [out] 要输出的元素数量。
• const right_shift_t shr – [out] 64 位乘积右移的位数。