Attention
=================

多头缩放点积注意力机制（Scaled Dot-Product Attention）

.. math::

    \text{Attention}(Q, K, V) = \operatorname{softmax}\left(\frac{Q K^\top}{\sqrt{d_k}}\right) V

输入：
    - **Q** - 查询矩阵地址（行优先），形状 :math:`[B, H, L, D]` 展平。
    - **K** - 键矩阵地址（行优先），形状 :math:`[B, H, L, D]` 展平。
    - **V** - 值矩阵地址（行优先），形状 :math:`[B, H, L, D]` 展平。
    - **params** - 其余参数打包成数组。
    - **core_mask（可选）** - 核掩码（仅适用于共享存储版本）。

输出：
    - **output** - 输出地址（行优先），形状 :math:`[B, H, L, D]` 展平。

支持平台：
    ``FT78NE``
    ``MT7004``

.. note::
    - 当前实现基于 fp32；输入/中间/输出缓冲区不应重叠。
    - 内存布局为行优先（row-major）。


**参数数组结构：**

.. code-block:: c
    :linenos:

    int params[10];
    params[0] = batch_size; 批大小
    params[1] = seq_len; 序列长度
    params[2] = head_num; 多头数量
    params[3] = head_dim; 每头通道维数
    params[4] = QK地址的低32位;
    params[5] = QK地址的高32位;
    params[6] = 中间缓冲区地址的低32位;
    params[7] = 中间缓冲区地址的高32位;

**共享存储版本：**

.. c:function:: void fp_attention_s(float *Q, float *K, float *V, float *output, int *params, int core_mask)

    **C调用示例：**

    .. code-block:: c
        :linenos:
        :emphasize-lines: 13

        #include <stdio.h>
        
        int main(int argc, char* argv[]) {
            int B = 2, L = 128, H = 8, D = 64;
            float *Q = (float *)0xA0000000;      // DDR
            float *K = (float *)0xA1000000;      // DDR
            float *V = (float *)0xA2000000;      // DDR
            float *O = (float *)0xA3000000;      // DDR
            float *QK = (float *)0xA4000000;     // DDR
            float *SM = (float *)0xA5000000;     // DDR
            int core_mask = 0xff;
            int params[10];
            params[0] = B;
            params[1] = L;
            params[2] = H;
            params[3] = D;
            params[4] = (int) (uint32_t) (uintptr_t) QK;
            params[5] = (int) (uint32_t) (uintptr_t) QK >> 32;
            params[6] = (int) (uint32_t) (uintptr_t) SM;
            params[7] = (int) (uint32_t) (uintptr_t) SM >> 32;
            fp_attention_s(Q, K, V, O, params, core_mask);
            return 0;
        }

**私有存储版本：**

.. c:function:: void fp_attention_p(float *Q, float *K, float *V, float *output, int *params)

    **C调用示例：**

    .. code-block:: c
        :linenos:
        :emphasize-lines: 12

        #include <stdio.h>
        
        int main(int argc, char* argv[]) {
            int B = 1, L = 64, H = 4, D = 32;
            float *Q = (float *)0x10000000;   // L2
            float *K = (float *)0x10040000;   // L2
            float *V = (float *)0x10080000;   // L2
            float *O = (float *)0x100C0000;   // L2
            float *QK = (float *)0x10100000;  // L2
            float *SM = (float *)0x10200000;  // L2
            int params[10];
            params[0] = B;
            params[1] = L;
            params[2] = H;
            params[3] = D;
            params[4] = (int) (uint32_t) (uintptr_t) QK;
            params[5] = (int) (uint32_t) (uintptr_t) QK >> 32;
            params[6] = (int) (uint32_t) (uintptr_t) SM;
            params[7] = (int) (uint32_t) (uintptr_t) SM >> 32;
            fp_attention_p(Q, K, V, O, params);
            return 0;
        }
