.. _kss-math-lib:

广义数学计算
======================

.. important::
   
    - 正确使用数学计算库需要用户具备一定的数学知识，且严格遵循API要求的输入/输出数据格式进行流程设计。
    - 我们鼓励用户在使用数学库前联系我司研发，表述实际需求，共同确认目标场景的可实施性。

工程配置
-----------------------

 - 链接器(Linker)设置：

    .. image:: ../../_static/kss-math-lib-linker-setting.png
     :align: center

 - 编译器(Compiler)设置：

    .. image:: ../../_static/kss-math-lib-compiler-setting.png
     :align: center

 - 用户代码设置：

    .. code-block:: c

     /* 在.c文件首包含以下头文件：*/
     #include "kss_math.h"

科学计算函数
-------------------------

API说明
^^^^^^^^^^^^^^^^^^^^^^^^^

.. c:macro:: PI_Q29

    圆周率 PI 对应的Q2.29有符号32位定点数表达。

.. c:macro:: ONE_Q29

    浮点数值 "1" 对应的Q2.29有符号32位定点数表达。

.. c:macro:: ONE_Q31

    浮点数值 "1" 对应的Q0.31有符号32位定点数表达。

.. c:function:: int32_t kss_cosine(int32_t phase);

    余弦函数。

    :param phase: 以Q2.29格式表示的弧度值，输入范围限定为[-PI_Q29, PI_Q29]。
    :returns: Q2.29格式的余弦值，输出范围为[-ONE_Q29, ONE_Q29]。

.. c:function:: int32_t kss_sine(int32_t phase);

    正弦函数。

    :param phase: 以Q2.29格式表示的弧度值，输入范围限定为[-PI_Q29, PI_Q29]。
    :returns: Q2.29格式的正弦值，输出范围为[-ONE_Q29, ONE_Q29]。

.. c:function:: int64_t kss_divlsl(int64_t dividend, int32_t divisor);

    64位有符号数除法。

    :param dividend: 64位有符号定点数作为被除数。
    :param divisor: 32位有符号定点数作为除数，需要确保0不会作为除数进行输入。
    :returns: 64位有符号定点数格式的商。

.. warning::
   
    - kss_divlsl()旨在为双字除法提供一种快速的近似解计算途径，如果需要精确解的场景，请务必使用编译器的原生除法“/”。


.. c:function:: int32_t kss_sqrt(int32_t val, int32_t * exponent);

    32位定点数平方根函数。

    :param val: 32位非负定点数输入。
    :param exponent: 32位定点数指针，用于保存平方根结果的指数部分(以2为底)。
    :returns: 平方根结果的系数部分(mantissa)，以Q2.29格式表示，输出范围为[ONE_Q29, 2*ONE_Q29)。
    :note: 
    
     1. 如果输入为0，输出的系数和指数部分均为0。
     2. 浮点数视角下，

      .. math::
      
       sqrt(\mathbf{val}) = \mathbf{mantissa} * 2^\mathbf{exponent} / 2^{29}

.. c:function:: int32_t kss_ln(int32_t mantissa_in, int32_t exponent_in, int32_t * exponent_out);

    Q31格式自然对数函数。

    :param mantissa_in: 输入数据的系数部分，Q31格式，范围为[ONE_Q31 / 2, ONE_Q31)。
    :param exponent_in: 输入数据的指数部分(以2为底)。
    :param exponent_out: 32位定点数指针，用于保存输出数据的指数部分(以2为底)。   
    :returns: 输出数据的系数部分，Q31格式，范围为[ONE_Q31 / 2, ONE_Q31)。
    :note: 
    
     1. 当输入为浮点数意义下的"1"时(mantissa = 0x40000000, exponent = 1)，输出系数和指数分别为0和-31。
     2. 推荐配合Q31格式化函数 :c:func:`kss_q31_formatter` 使用，其输出将保证 *kss_ln* 的输出非负。
     3. 浮点数视角下，

      .. math::
     
       ln(\mathbf{mantissa_in} * 2^\mathbf{exponent_in} / 2^{31}) = \mathbf{mantissa_out} * 2^\mathbf{exponent_out} / 2^{31}

.. c:function:: int32_t kss_smulps29(int32_t rs1, int32_t rs2);

    32位有符号数乘法，将64位结果进行算数右移29位后输出低32位数值。

    :param rs1: 被乘数。
    :param rs2: 乘数。
    :returns: 算数右移后的乘积。
    :note: 类似功能的函数还包括 *kss_smulps15/16/27/28/30/31/32()* 。 

.. c:function:: int32_t kss_q31_formatter(int32_t val, int32_t * exponent);

    将32位有符号数转化为Q31格式输出。

    :param val: 32位有符号数，必须为正数。
    :param exponent: 32位定点数指针，用于保存Q31格式输出数据的指数部分(以2为底)。
    :returns: Q31格式输出数据的系数部分，范围为[ONE_Q31 / 2, ONE_Q31)。

向量计算函数
-------------------------

API说明
^^^^^^^^^^^^^^^^^^^^^^^^^

.. c:function:: int32_t kss_vec_sum_of_squares(int32_t * vec, int32_t len, int32_t shift);

    .. math::

     SAT.INT32((\sum_{i=0}^{\mathbf{len}-1}\mathbf{vec}[i]^2)>>\mathbf{shift})

    向量元素平方求和函数。

    :param vec: 32位宽度输入向量vec的首地址。
    :param len: 输入向量vec的长度。
    :param shift: 原始求得平方和数值右移位数，0~31范围内有效。   
    :returns: 平方和经过右移和饱和处理后的结果。
    :note: 
    
     1. 输入向量vec的长度必须大于0。
     2. 输入向量vec元素的平方和必须落于INT64_MAX范围。
     3. 平方和经过右移后如果超过INT32_MAX范围，函数将输出饱和值 0x7FFFFFFF。

循环冗余校验(CRC)函数
-------------------------

.. important::
   
    - 本章节旨在提供一种基于SPV1x指令集，且不依赖静态表的CRC计算途径，请阅读各个函数的说明，充分了解其使用限制。

API说明
^^^^^^^^^^^^^^^^^^^^^^^^^

.. c:function:: uint32_t kss_crc32_aligned(uint8_t * data, int32_t len, uint32_t init);

    限定场景的CRC32计算函数。

    :param data: 字节数组形式的输入数据序列。
    :param len: 输入数据的长度，以字节为单位。
    :param init: CRC32初始值。   
    :returns: CRC32计算结果。
    :note: 
    
     1. 输入数据 *data* 必须对齐到4字节地址，可以使用预定义宏 *__ALIGNED(4)* 进行修饰。
     2. 输入数据 *data* 的字节长度 *len* 必须大于0。
     3. 此CRC32计算函数固定使用 *Poly = 0x04C11DB7* 作为生成多项式。
     4. 此函数不支持设置输入/输出数据反转功能(RefIn/RefOut)。

.. c:function:: uint16_t kss_crc16_aligned(uint8_t * data, int32_t len, uint16_t init);

    限定场景的CRC16计算函数。

    :param data: 字节数组形式的输入数据序列。
    :param len: 输入数据的长度，以字节为单位。
    :param init: CRC16初始值。   
    :returns: CRC16计算结果。
    :note: 
    
     1. 输入数据 *data* 必须对齐到4字节地址，可以使用预定义宏 *__ALIGNED(4)* 进行修饰。
     2. 输入数据 *data* 的字节长度 *len* 必须大于0。
     3. 此CRC16计算函数固定使用 *Poly = 0x1021* 作为生成多项式。
     4. 此函数不支持设置输入/输出数据反转功能(RefIn/RefOut)。