docs:The documentation for the Conv Operator

infiniop/ops/conv/README.md

@@ -0,0 +1,158 @@
+# `Conv`
+
+`Conv`，即**卷积**算子。计算过程可表示为对输入特征图应用卷积核进行空间域的滑动窗口计算，是深度学习中的基础操作。
+
+$$ Y = \text{Conv}(X, W) + \text{bias} $$
+
+其中：
+
+- `X` 为输入特征图，形状为 `(N, C_in, D_1, D_2, ...)`。
+- `W` 为卷积核权重，形状为 `(C_out, C_in/groups, K_1, K_2, ...)`。
+- `bias` 为偏置项，形状为 `(1, C_out, 1, 1, ...)`。
+- `Y` 为输出特征图，形状为 `(N, C_out, D_out_1, D_out_2, ...)`。
+- 相关参数包括 `pads`, `strides`, `dilations` 等控制卷积操作细节。
+
+## 接口
+
+### 计算
+
+```c
+infiniStatus_t infiniopConv(
+    infiniopConvDescriptor_t desc,
+    void *workspace,
+    size_t workspace_size,
+    void *y,
+    const void *x,
+    const void *w,
+    const void *bias,
+    void *stream
+);
+```
+
+<div style="background-color: lightblue; padding: 1px;"> 参数： </div>
+
+- `desc`:
+  已使用 `infiniopCreateConvDescriptor()` 初始化的算子描述符。
+- `workspace`:
+  指向算子计算所需的额外工作空间。
+- `workspace_size`:
+  `workspace` 的大小，单位：字节。
+- `y`:
+  计算输出结果。张量限制见创建算子描述部分。
+- `x`:
+  输入特征图。张量限制见创建算子描述部分。
+- `w`:
+  卷积权重。张量限制见创建算子描述部分。
+- `bias`:
+  卷积偏置。张量限制见创建算子描述部分。
+- `stream`:
+  计算流/队列。
+
+<div style="background-color: lightblue; padding: 1px;">  返回值：</div>
+
+- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_BAD_PARAM`], [`INFINI_STATUS_INSUFFICIENT_WORKSPACE`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`], [`INFINI_STATUS_INTERNAL_ERROR`].
+
+### 创建算子描述
+
+```c
+infiniStatus_t infiniopCreateConvDescriptor(
+    infiniopHandle_t handle,
+    infiniopConvDescriptor_t *desc_ptr,
+    infiniopTensorDescriptor_t y,
+    infiniopTensorDescriptor_t x,
+    infiniopTensorDescriptor_t w,
+    infiniopTensorDescriptor_t b,
+    void *pads,
+    void *strides,
+    void *dilations,
+    size_t n
+);
+```
+
+<div style="background-color: lightblue; padding: 1px;"> 参数：</div>
+
+- `handle`:
+  `infiniopHandle_t` 类型的硬件控柄。详情请看：[`InfiniopHandle_t`]
+- `desc_ptr`:
+  指向将被初始化的算子描述符地址；
+- `y` - { dT | (N, C_out, D_out_1, D_out_2, ...) | (~) }:
+  算子计算参数 `y` 的张量描述。
+- `x` - { dT | (N, C_in, D_1, D_2, ...) | (~) }:
+  算子计算参数 `x` 的张量描述。
+- `w` - { dT | (C_out, C_in/groups, K_1, K_2, ...) | (~) }:
+  算子计算参数 `w` 的张量描述。
+- `b` - { dT | (1, C_out, 1, 1, ...) | (~) }:
+  算子计算参数 `b` 的张量描述，即卷积偏置项。
+- `pads` - void*:
+  输入特征图填充大小的指针，数组长度为 `2*n`，表示每个空间维度的前后填充。
+- `strides` - void*:
+  卷积滑动步长的指针，数组长度为 `n`。
+- `dilations` - void*:
+  卷积膨胀率的指针，数组长度为 `n`。
+- `n` - size_t:
+  空间维度数量。
+
+<div style="background-color: lightblue; padding: 1px;"> 参数限制：</div>
+
+参数限制：
+
+- `dT`: (`Float16`, `Float32`) 之一；
+- `N`: 批量大小，N > 0；
+- `C_in`: 输入通道数，C_in > 0；
+- `C_out`: 输出通道数，C_out > 0；
+- `D_i`: 输入特征图的第i个维度，D_i > 0；
+- `K_i`: 卷积核的第i个维度，K_i > 0；
+- `n`: 空间维度数量，通常为 2（2D卷积）或 3（3D卷积）；
+
+<div style="background-color: lightblue; padding: 1px;"> 返回值：</div>
+
+- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_BAD_PARAM`], [`INFINI_STATUS_BAD_TENSOR_SHAPE`], [`INFINI_STATUS_BAD_TENSOR_DTYPE`], [`INFINI_STATUS_BAD_TENSOR_STRIDES`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`].
+
+### 计算额外工作空间
+
+```c
+infiniStatus_t infiniopGetConvWorkspaceSize(
+    infiniopConvDescriptor_t desc,
+    size_t *size
+);
+```
+
+<div style="background-color: lightblue; padding: 1px;"> 参数：</div>
+
+- `desc`:
+  已使用 `infiniopCreateConvDescriptor()` 初始化的算子描述符。
+- `size`:
+  额外空间大小的计算结果的写入地址；
+
+<div style="background-color: lightblue; padding: 1px;"> 返回值：</div>
+
+- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_BAD_PARAM`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`].
+
+### 销毁算子描述符
+
+```c
+infiniStatus_t infiniopDestroyConvDescriptor(
+    infiniopConvDescriptor_t desc
+);
+```
+
+<div style="background-color: lightblue; padding: 1px;"> 参数： </div>
+
+- `desc`:
+  输入。待销毁的算子描述符；
+
+<div style="background-color: lightblue; padding: 1px;"> 返回值： </div>
+
+- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`].
+
+<!-- 链接 -->
+[`InfiniopHandle_t`]: README.md
+
+[`INFINI_STATUS_SUCCESS`]:/common/status/README.md#INFINI_STATUS_SUCCESS
+[`INFINI_STATUS_BAD_PARAM`]:/common/status/README.md#INFINI_STATUS_BAD_PARAM
+[`INFINI_STATUS_INSUFFICIENT_WORKSPACE`]:/common/status/README.md#INFINI_STATUS_INSUFFICIENT_WORKSPACE
+[`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`]:/common/status/README.md#INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED
+[`INFINI_STATUS_INTERNAL_ERROR`]:/common/status/README.md#INFINI_STATUS_INTERNAL_ERROR
+[`INFINI_STATUS_BAD_TENSOR_SHAPE`]:/common/status/README.md#INFINI_STATUS_BAD_TENSOR_SHAPE
+[`INFINI_STATUS_BAD_TENSOR_DTYPE`]:/common/status/README.md#INFINI_STATUS_BAD_TENSOR_DTYPE
+[`INFINI_STATUS_BAD_TENSOR_STRIDES`]:/common/status/README.md#INFINI_STATUS_BAD_TENSOR_STRIDES

infiniop/ops/softmax/README.md

@@ -1,4 +1,3 @@
-
 # `Softmax`
 
 归一化指数函数，常用于讲输入数据转换为概率分布。对于长度为 $N$ 的一维张量 $x$ ，其公式为：
@@ -14,6 +13,8 @@ $$ y_i = \frac{e^{x_i}}{\sum_{i=0}^{N - 1} e^{x_i}} $$
 ```c
 infiniStatus_t infiniopSoftmax(
     infiniopSoftmaxDescriptor_t desc, 
+    void *workspace,
+    size_t workspace_size,
     void *y, 
     const void *x, 
     void *stream
@@ -23,6 +24,8 @@ infiniStatus_t infiniopSoftmax(
 <div style="background-color: lightblue; padding: 1px;"> 参数： </div>
 
 - `desc`：已使用 `infiniopCreateSoftmaxDescriptor()` 初始化的算子描述符。
+- `workspace`：工作空间指针。
+- `workspace_size`：工作空间大小。
 - `y`：输出指针。
 - `x`：输入指针，可以与 `y` 相同。
 - `stream`：计算流/队列。
@@ -33,7 +36,7 @@ infiniStatus_t infiniopSoftmax(
 
 ---
 
-### 创建算子描述
+### 创建算子描述符
 
 ```c
 infiniStatus_t infiniopCreateSoftmaxDescriptor(
@@ -63,6 +66,26 @@ infiniStatus_t infiniopCreateSoftmaxDescriptor(
 
 ---
 
+### 获取工作空间大小
+
+```c
+infiniStatus_t infiniopGetSoftmaxWorkspaceSize(
+    infiniopSoftmaxDescriptor_t desc,
+    size_t *size
+);
+```
+
+<div style="background-color: lightblue; padding: 1px;"> 参数： </div>
+
+- `desc`：已使用 `infiniopCreateSoftmaxDescriptor()` 初始化的算子描述符。
+- `size`：返回所需工作空间大小的指针。
+
+<div style="background-color: lightblue; padding: 1px;">  返回值：</div>
+
+- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`]
+
+---
+
 ### 销毁算子描述符
 
 ```c
@@ -73,19 +96,12 @@ infiniStatus_t infiniopDestroySoftmaxDescriptor(
 
 <div style="background-color: lightblue; padding: 1px;"> 参数： </div>
 
-- `desc`
-     : 待销毁的算子描述符。
+- `desc`: 待销毁的算子描述符。
 
 <div style="background-color: lightblue; padding: 1px;"> 返回值： </div>
 
 - [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`].
 
-## 已知问题
-
-### 平台限制
-
-- 寒武纪中 tensor.to(device) 的 tensor 不支持 uint64 或者是 int64 数据类型。
-
 <!-- 链接 -->
 [`InfiniopHandle_t`]: /infiniop/handle/README.md
 
@@ -94,4 +110,4 @@ infiniStatus_t infiniopDestroySoftmaxDescriptor(
 [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`]: /common/status/README.md#INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED
 [`INFINI_STATUS_BAD_TENSOR_SHAPE`]: /common/status/README.md#INFINI_STATUS_BAD_TENSOR_SHAPE
 [`INFINI_STATUS_BAD_TENSOR_DTYPE`]: /common/status/README.md#INFINI_STATUS_BAD_TENSOR_DTYPE
-[`INFINI_STATUS_BAD_TENSOR_STRIDES`]: /common/status/README.md#INFINI_STATUS_BAD_TENSOR_STRIDES
+[`INFINI_STATUS_BAD_TENSOR_STRIDES`]: /common/status/README.md#INFINI_STATUS_BAD_TENSOR_STRIDES