diff --git a/InfiniCore-doc/README.md b/InfiniCore-doc/README.md new file mode 100644 index 0000000000000000000000000000000000000000..0ffb4f48b487eeea65677025ba8f81a799492e39 --- /dev/null +++ b/InfiniCore-doc/README.md @@ -0,0 +1,19 @@ +# InfiniCore 文档 + +## 项目简介 + +*InfiniCore* 是一个跨平台统一编程工具集，为不同芯片平台的功能（包括计算、运行时、通信等）提供统一 C 语言接。 + +项目地址： + +## 文档目录 + +*InfiniCore* 包含以下几个模块： + +- [`InfiniRT`]：统一运行时库，提供基础的运行时功能，包括线程、内存管理、同步、事件通知等。 +- [`InfiniOP`]：统一算子库，提供各类基于张量的高性能算子计算功能。 +- [`InfiniCCL`]：统一集合通信库，提供常用的集合通信功能，包括点对点、广播、聚合等。 + +[`InfiniRT`]:/infinirt/README.md +[`InfiniOP`]:/infiniop/README.md +[`InfiniCCL`]:/infiniccl/README.md diff --git a/InfiniCore-doc/common/device/README.md b/InfiniCore-doc/common/device/README.md new file mode 100644 index 0000000000000000000000000000000000000000..9f9848ccc0a8a8916578acd000a2541970ac1ab2 --- /dev/null +++ b/InfiniCore-doc/common/device/README.md @@ -0,0 +1,13 @@ +# 硬件类型（`infiniDevice_t`） + +| 常量名称 | 数值 | 硬件类型 | +|------------------------|:-------:|:----------------------:| +| INFINI_DEVICE_CPU | 0 | CPU | +| INFINI_DEVICE_NVIDIA | 1 | 英伟达 | +| INFINI_DEVICE_CAMBRICON | 2 | 寒武纪 | +| INFINI_DEVICE_ASCEND | 3 | 昇腾 | +| INFINI_DEVICE_METAX | 4 | 沐曦 | +| INFINI_DEVICE_MOORE | 5 | 摩尔线程 | +| INFINI_DEVICE_ILUVATAR | 6 | 天数智芯 | +| INFINI_DEVICE_KUNLUN | 7 | 昆仑 | +| INFINI_DEVICE_SUGON | 8 | 曙光 | diff --git a/InfiniCore-doc/common/dtype/README.md b/InfiniCore-doc/common/dtype/README.md new file mode 100644 index 0000000000000000000000000000000000000000..3e17ca4f76b76e70aab83d39044138591d817ac2 --- /dev/null +++ b/InfiniCore-doc/common/dtype/README.md @@ -0,0 +1,24 @@ +# 数据类型（`infiniDtype_t`） + +| 常量名称 | 数值 | 数据类型 | +|-----------------------|:------:|------------------| +| INFINI_DTYPE_INVALID | 0 | 非法类型 | +| INFINI_DTYPE_BYTE | 1 | Byte: 字节 | +| INFINI_DTYPE_BOOL | 2 | Boolean: 布尔 | +| INFINI_DTYPE_I8 | 3 | Int8: 8位整数 | +| INFINI_DTYPE_I16 | 4 | Int16: 16位整数 | +| INFINI_DTYPE_I32 | 5 | Int32: 32位整数 | +| INFINI_DTYPE_I64 | 6 | Int64: 64位整数 | +| INFINI_DTYPE_U8 | 7 | Uint8: 8位自然数 | +| INFINI_DTYPE_U16 | 8 | Uint16: 16位自然数 | +| INFINI_DTYPE_U32 | 9 | Uint32: 32位自然数 | +| INFINI_DTYPE_U64 | 10 | Uint64: 64位自然数 | +| INFINI_DTYPE_F8 | 11 | Float8: 8位浮点数 | +| INFINI_DTYPE_F16 | 12 | Float16: 16位浮点数 | +| INFINI_DTYPE_F32 | 13 | Float32: 32位浮点数 | +| INFINI_DTYPE_F64 | 14 | Float64: 64位浮点数 | +| INFINI_DTYPE_C16 | 15 | Complex16: 16位复数 | +| INFINI_DTYPE_C32 | 16 | Complex32: 32位复数 | +| INFINI_DTYPE_C64 | 17 | Complex64: 64位复数 | +| INFINI_DTYPE_C128 | 18 | Complex128 128位复数 | +| INFINI_DTYPE_BF16 | 19 | BFloat16: 16位Brain浮点数 | diff --git a/InfiniCore-doc/common/status/README.md b/InfiniCore-doc/common/status/README.md new file mode 100644 index 0000000000000000000000000000000000000000..ae79d5f8ed5e4f288e0586b7bbcdc088035d3853 --- /dev/null +++ b/InfiniCore-doc/common/status/README.md @@ -0,0 +1,81 @@ +# 接口调用结果代码（`infiniStatus_t`） + +*InfiniCore* 库中所有的API均会返回接口调用结果，用来表示调用是否成果以及错误类型。各类返回值以及含义如下： + + + +- INFINI_STATUS_SUCCESS = 0 + + 运行成功。 + + + +- INFINI_STATUS_INTERNAL_ERROR = 1 + + 硬件内部/底层功能错误。如果错误来源是硬件平台提供的编程库，会打印出该库的错误代码，详细错误原因需要去相应厂商提供的文档中查询。 + + + +- INFINI_STATUS_NOT_IMPLEMENTED = 2 + + 接口功能尚未实现。 + + + +- INFINI_STATUS_BAD_PARAM = 3 + + 传入的参数（组合）不符合接口限制。 + + + +- INFINI_STATUS_NULL_POINTER = 4 + + 需要有效的地址的参数被传入了空指针。 + + + +- INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED = 5 + + 接口不支持用户所指定的硬件类型。 + + + +- INFINI_STATUS_DEVICE_NOT_FOUND = 6 + + 无法找到用户指定的硬件类型与硬件序号所指向的设备。 + + + +- INFINI_STATUS_DEVICE_NOT_INITIALIZED = 7 + + 设备未被初始化。请检查硬件驱动是否正常，以及是否调用了相应计算库的初始化接口。 + + + +- INFINI_STATUS_DEVICE_ARCHITECTURE_NOT_SUPPORTED = 8 + + 未被支持的硬件的架构。一些硬件类型包含不同型号以及硬件特性的设备，该型号不被接口支持。 + + + +- INFINI_STATUS_BAD_TENSOR_DTYPE = 10 + + 用户传入的设备类型不支持。 + + + +- INFINI_STATUS_BAD_TENSOR_SHAPE = 11 + + 用户传入的张量形状不支持。 + + + +- INFINI_STATUS_BAD_TENSOR_STRIDES = 12 + + 用户传入的张量步长不支持。 + + + +- INFINI_STATUS_INSUFFICIENT_WORKSPACE = 13 + + 用户传入的工作空间大小不足。 diff --git a/InfiniCore-doc/infiniccl/README.md b/InfiniCore-doc/infiniccl/README.md new file mode 100644 index 0000000000000000000000000000000000000000..ffacbea038d643006677645c54220fb95adabfe1 --- /dev/null +++ b/InfiniCore-doc/infiniccl/README.md @@ -0,0 +1,64 @@ + +# `infiniccl`统一集合通信库 + +## 简介 + + `InfiniCCL`：统一集合通信库，提供常用的集合通信功能，包括点对点、广播、聚合等。 + +## 编程接口 +#### 初始化通信组 + +``` c++ +infiniStatus_t infinicclCommInitAll( + infiniDevice_t device_type, + infinicclComm_t *comms, + int ndevice, + const int *device_ids); +``` + +- device_type: 设备类型，枚举类型 infiniDevice_t，例如 INFINI_DEVICE_NVIDIA。 +- comms: 输出通信组句柄数组，长度为 ndevice。 +- ndevice: 设备数量。 +- device_ids: 设备 ID 数组，长度为 ndevice，每个 ID 对应 device_type 类型下的一个设备。 +- 说明：为指定设备类型的若干设备创建通信上下文，用于后续 AllReduce 等 collective 操作。每个设备对应一个通信句柄。 + +#### 销毁通信组 + +``` c++ +infiniStatus_t infinicclCommDestroy(infinicclComm_t comm); +``` + +- comm: 需要销毁的通信组句柄。 +- 说明：释放通过 infinicclCommInitAll 创建的通信资源。 + +#### AllReduce 操作 + +``` c++ +infiniStatus_t infinicclAllReduce( + void *sendbuf, + void *recvbuf, + size_t count, + infiniDtype_t datatype, + infinicclReduceOp_t op, + infinicclComm_t comm, + infinirtStream_t stream); +``` + +- sendbuf: 输入缓冲区，存放需要参与 AllReduce 的本地数据。 +- recvbuf: 输出缓冲区，存放归约后的结果数据。 +- count: 元素个数（而不是字节数）。 +- datatype: [枚举类型infiniDtype_t](/common/dtype/README.md)。 +- op: 归约操作类型，枚举类型 infinicclReduceOp_t。 + 其定义如下: +``` + typedef enum { + INFINICCL_SUM = 0, + INFINICCL_PROD = 1, + INFINICCL_MAX = 2, + INFINICCL_MIN = 3, + INFINICCL_AVG = 4, +} infinicclReduceOp_t; +``` +- comm: 通信组句柄。 +- stream: 指定操作执行在哪个 infinirtStream_t 流上。 +- 说明：在通信组内所有设备上执行 AllReduce 操作。各设备的 recvbuf 将接收到相同的归约结果。 diff --git a/InfiniCore-doc/infiniop/README.md b/InfiniCore-doc/infiniop/README.md new file mode 100644 index 0000000000000000000000000000000000000000..1921c7889e0cc1d8e7baf0313789424b8f63b0db --- /dev/null +++ b/InfiniCore-doc/infiniop/README.md @@ -0,0 +1,50 @@ +# `InfiniOP` 统一算子库 + +## 简介 + +*InfiniOP* 是一个跨平台统一的高性能算子库。它使得开发者可以通过统一的编程接口，使用不同类型的芯片的算力资源进行高性能的算子运算。*InfiniOP* 统一算子库的编译与使用依赖于 [`InifiniRT`] 统一运行时库。 + +## 算子计算流程 + +### 1. 创建硬件控柄 + +*InfiniOP* 使用硬件控柄（[`infiniopHandle_t`]）来存储一些算子运算所需要的、与硬件芯片相关的信息。开发者通过创建并传入的相应类型、标识的硬件控柄来告诉算子使用环境中的哪种类型的哪个芯片进行运算。 + +### 2. 创建张量描述 + +当一个算子以高维张量作为输入或输出时，开发者需要使用张量描述（[`infiniopTensorDescriptor_t`]）来描述该张量的形状、数据类型、以及数据布局（各维度的步长）信息。 + +### 3. 创建算子描述 + +通过硬件控柄和输入输出的张量描述，创建算子描述。当执行硬件和张量元信息不变时（只有张量数据改变时），可以复用算子描述。 + +### 4. 分配工作空间 + +一些算子需要额外的工作空间来存储中间结果。开发者可以从创建好的算子描述中获取需要的工作空间大小，并分配相应的空间。 + +### 5. 计算 + +通过传入算子描述、输入输出张量描述所对应的张量数据、以及分配好的工作空间、硬件执行流等参数，执行算子计算。 + +## 使用 InfiniOP API + +### 错误处理 + +*InfiniOP* 的所有API都会返回 [`InfiniStatus_t`]，用来表示函数执行的是否成功以及错误的原因。 + +### 运行时 + +*InfiniOP* 依赖于 [`InifiniRT`] 统一运行时库提供的硬件资源管理功能，包括切换设备上下文、分配和释放内存、创建执行流等。使用 *InfiniOP* 接口并不会自动切换设备上下文。 + +### 资源的复用与释放 + +算子描述、张量描述、硬件控柄都是可以被复用的。开发者应该尽可能的复用这些资源，以避免资源的重复创建带来的冗余开销。当算子计算完成后，开发者可以销毁不再被需要的算子描述、张量描述、硬件控柄。需要注意的是，硬件控柄以及一些算子的算子描述会包含一些计算所需的资源，由于算子的计算可以是异步的，开发者需要自行保证这些资源的销毁发生在计算完成之后，以避免错误行为。 + +## 算子列表 + +详见 [InfiniOP算子列表](/infiniop/ops/README.md) + +[`InifiniRT`]:/ +[`infiniopHandle_t`]:/infiniop/handle/README.md +[`infiniopTensorDescriptor_t`]:/infiniop/tensor/README.md +[`InfiniStatus_t`]:/common/status/README.md diff --git a/InfiniCore-doc/infiniop/handle/README.md b/InfiniCore-doc/infiniop/handle/README.md new file mode 100644 index 0000000000000000000000000000000000000000..9600e0db913260307ec281e9c1d4f1b3e43c8b9b --- /dev/null +++ b/InfiniCore-doc/infiniop/handle/README.md @@ -0,0 +1,38 @@ +# 硬件控柄（`infiniopHandle_t`） + +*InfiniOP* 是一个支持多种硬件的跨平台算子库，用户在创建算子时，需要首先创建并传入对应的硬件控柄（`infiniopHandle_t`），以便于算子构建出正确的计算函数。每一个硬件控柄会唯一对应一个硬件，例如在一个一机多卡的环境中，每张卡都需要有自己独立的硬件控柄才能在对应的卡上执行计算。在同一个硬件上构建多个算子时，推荐重复使用同一个硬件控柄以减少开销。硬件控柄是线程安全的。 + +用户创建硬件控柄时，需要预先使用 *InfiniRT* 运行时库中的 [`infinirtSetDevice`] 接口来指定硬件设备。需要注意的是，使用硬件控柄（包括算子计算）时，算子库不会自动切换硬件的运行时上下文（Context）。当用户在一个线程上对多个硬件进行操作（包括构建算子描述和执行计算）时，需自行调用 [`infinirtSetDevice`] 接口切换设备，以保证算子库接口在指定的硬件设备上的正确运行。推荐用户使用“一个线程对应一个硬件”的程序设计避免复杂的硬件管理。 + +## 接口 + +### 创建硬件控柄 + +```c +infiniStatus_t infiniopCreateHandle(infiniopHandle_t *handle_ptr); +``` + +- `handle_ptr`: 存储将被创建的硬件控柄的地址； + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_NULL_POINTER`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`], [`INFINI_STATUS_INTERNAL_ERROR`] + +### 销毁硬件控柄 + +```c +infiniStatus_t infiniopDestroyHandle(infiniopHandle_t handle); +``` + +- `handle`: 将被销毁的硬件控柄； + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`] + + +[`infinirtSetDevice`]: / +[`INFINI_STATUS_SUCCESS`]: /common/status/README.md#INFINI_STATUS_SUCCESS +[`INFINI_STATUS_NULL_POINTER`]: /common/status/README.md#INFINI_STATUS_NULL_POINTER +[`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 diff --git a/InfiniCore-doc/infiniop/ops/README.md b/InfiniCore-doc/infiniop/ops/README.md new file mode 100644 index 0000000000000000000000000000000000000000..0633ec669d50c590de362bf8eb6f63f2f4492cc0 --- /dev/null +++ b/InfiniCore-doc/infiniop/ops/README.md @@ -0,0 +1,14 @@ +# `InfiniOP` 算子列表 + +- [`Add`](/infiniop/ops/add/README.md) +- [`Causal Softmax`](/infiniop/ops/causal_softmax/README.md) +- [`Clip`](/infiniop/ops/clip/README.md) +- [`GEMM`](/infiniop/ops/gemm/README.md) +- [`Mul`](/infiniop/ops/mul/README.md) +- [`Random Sample`](/infiniop/ops/random_sample/README.md) +- [`Rearrange`](/infiniop/ops/rearrange/README.md) +- [`RMS Norm`](/infiniop/ops/rms_norm/README.md) +- [`RoPE`](/infiniop/ops/rope/README.md) +- [`Softmax`](/infiniop/ops/softmax/README.md) +- [`Sub`](/infiniop/ops/sub/README.md) +- [`SwiGLU`](/infiniop/ops/swiglu/README.md) diff --git a/InfiniCore-doc/infiniop/ops/add/README.md b/InfiniCore-doc/infiniop/ops/add/README.md new file mode 100644 index 0000000000000000000000000000000000000000..37b55716ec0cf3e08d0e88eaf413b20c56e5c0d2 --- /dev/null +++ b/InfiniCore-doc/infiniop/ops/add/README.md @@ -0,0 +1,135 @@ + +# `Add` + +`Add`, 即**加法**算子，为双目逐元素算子。其计算可被表述为： + +$$ c = a + b $$ + +其中 `a` 和 `b` 为输入，`c` 为输出。 + +## 接口 + +### 计算 + +```c +infiniStatus_t infiniopAdd( + infiniopAddDescriptor_t desc, + void *workspace, + size_t workspace_size, + void *c, + const void *a, + const void *b, + void *stream +); +``` + +
参数：
+ +- `desc`: + 已使用 `infiniopCreateAddDescriptor()` 初始化的算子描述符； +- `workspace`: + 指向算子计算所需的额外工作空间； +- `workspace_size`: + `workspace` 的大小，单位：字节； +- `c`: + 输出张量。张量限制见[创建算子描述](#创建算子描述)部分； +- `a`: + 输入张量。张量限制见[创建算子描述](#创建算子描述)部分； +- `b`: + 输入张量。张量限制见[创建算子描述](#创建算子描述)部分； +- `stream`: + 计算流/队列； + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_BAD_PARAM`], [`INFINI_STATUS_INSUFFICIENT_WORKSPACE`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`], [`INFINI_STATUS_INTERNAL_ERROR`]，[`INFINI_STATUS_BAD_TENSOR_DTYPE`]. + +### 创建算子描述 + +```c +infiniStatus_t infiniopCreateAddDescriptor( + infiniopHandle_t handle, + infiniopAddDescriptor_t *desc_ptr, + infiniopTensorDescriptor_t c_desc, + infiniopTensorDescriptor_t a_desc, + infiniopTensorDescriptor_t b_desc +); +``` + +
参数：
+ +- `handle`: + `infiniopHandle_t` 类型的硬件控柄。详情请看：[`InfiniopHandle_t`]。 +- `desc_ptr`: + `infiniopAddDescriptor_t` 指针，指向将被初始化的算子描述符地址； +- `c_desc` - { dT | (d1,...,dn) | (...) }: + 算子计算参数 `c` 的张量描述，支持原位计算。 +- `a_desc` - { dT | (d1,...,dn) | (...) }: + 算子计算参数 `a` 的张量描述，支持原位计算，支持多向广播。 +- `b_desc` - { dT | (d1,...,dn) | (...) }: + 算子计算参数 `b` 的张量描述，支持原位计算，支持多向广播。 + +参数限制： + +- `dT`: (`Float16`, `Float32`, `Float64`, `BFloat16`) 之一。 +- 输入 `a` 与 `b` 的形状需与 `c` 相同。`a` 与 `b` 涉及多向广播时需调整步长以匹配多向广播的映射关系。 +- 支持原位计算，即计算时 `c` 可以和 `a` 或 `b` 指向同一地址。 +- 计算输出参数 `c` 不能进行广播（`c` 的步长不能涉及广播设置，即步长不能有 0） + +
返回值：
+ +- [`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 infiniopGetAddWorkspaceSize( + infiniopAddDescriptor_t desc, + size_t *size +); +``` + +
参数：
+ +- `desc`: + 已使用 `infiniopCreateAddDescriptor()` 初始化的算子描述符； +- `size`: + 额外空间大小的计算结果的写入地址； + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_NULL_POINTER`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`]. + +### 销毁算子描述符 + +```c +infiniStatus_t infiniopDestroyAddDescriptor( + infiniopAddDescriptor_t desc +); +``` + +
参数：
+ +- `desc`: + 输入。 待销毁的算子描述符； + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`]. + +## 已知问题 + +无 + + +[`InfiniopHandle_t`]: /infiniop/handle/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_NULL_POINTER`]: /common/status/README.md#INFINI_STATUS_NULL_POINTER +[`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 diff --git a/InfiniCore-doc/infiniop/ops/cast/README.md b/InfiniCore-doc/infiniop/ops/cast/README.md new file mode 100644 index 0000000000000000000000000000000000000000..f2f8899223bd23df9f8dc84f816a5f7d74abb87e --- /dev/null +++ b/InfiniCore-doc/infiniop/ops/cast/README.md @@ -0,0 +1,130 @@ +# `Cast` + +`Cast`, 即**类型转换**算子，用于将输入张量的数据类型转换为指定的目标数据类型。其计算可被表述为： + +$$ output = cast(input, target\_dtype) $$ + +其中 `input` 为输入张量，`output` 为输出张量，`target_dtype` 为目标数据类型。 + +## 接口 + +### 计算 + +```c +infiniStatus_t infiniopCast( + infiniopCastDescriptor_t desc, + void *workspace, + size_t workspace_size, + void *output, + const void *input, + void *stream +); +``` + +
参数：
+ +- `desc`: + 已使用 `infiniopCreateCastDescriptor()` 初始化的算子描述符； +- `workspace`: + 指向算子计算所需的额外工作空间； +- `workspace_size`: + `workspace` 的大小，单位：字节； +- `output`: + 输出张量。张量限制见[创建算子描述](#创建算子描述)部分； +- `input`: + 输入张量。张量限制见[创建算子描述](#创建算子描述)部分； +- `stream`: + 计算流/队列； + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_BAD_PARAM`], [`INFINI_STATUS_INSUFFICIENT_WORKSPACE`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`], [`INFINI_STATUS_INTERNAL_ERROR`]，[`INFINI_STATUS_BAD_TENSOR_DTYPE`]. + +### 创建算子描述 + +```c +infiniStatus_t infiniopCreateCastDescriptor( + infiniopHandle_t handle, + infiniopCastDescriptor_t *desc_ptr, + infiniopTensorDescriptor_t output, + infiniopTensorDescriptor_t input +); +``` + +
参数：
+ +- `handle`: + `infiniopHandle_t` 类型的硬件控柄。详情请看：[`InfiniopHandle_t`]。 +- `desc_ptr`: + `infiniopCastDescriptor_t` 指针，指向将被初始化的算子描述符地址； +- `output` - { dT_out | (d1,...,dn) | (...) }: + 算子计算参数 `output` 的张量描述。 +- `input` - { dT_in | (d1,...,dn) | (...) }: + 算子计算参数 `input` 的张量描述。 + +参数限制： + +- `dT_in`, `dT_out`: 支持以下类型转换： + - 整数类型间互转：`Int8`, `Int16`, `Int32`, `Int64`, `UInt8`, `UInt16`, `UInt32`, `UInt64` + - 浮点类型间互转：`Float16`, `Float32`, `Float64`, `BFloat16` + - 整数转浮点：从上述整数类型转换为上述浮点类型 +- 输入 `input` 与输出 `output` 的形状需相同。 +- 不支持原位计算，即计算时 `output` 不能和 `input` 指向同一地址。 + +
返回值：
+ +- [`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 infiniopGetCastWorkspaceSize( + infiniopCastDescriptor_t desc, + size_t *size +); +``` + +
参数：
+ +- `desc`: + 已使用 `infiniopCreateCastDescriptor()` 初始化的算子描述符； +- `size`: + 额外空间大小的计算结果的写入地址； + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_NULL_POINTER`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`]. + +### 销毁算子描述符 + +```c +infiniStatus_t infiniopDestroyCastDescriptor( + infiniopCastDescriptor_t desc +); +``` + +
参数：
+ +- `desc`: + 输入。 待销毁的算子描述符； + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`]. + +## 已知问题 + +无 + + +[`InfiniopHandle_t`]: /infiniop/handle/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_NULL_POINTER`]: /common/status/README.md#INFINI_STATUS_NULL_POINTER +[`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 \ No newline at end of file diff --git a/InfiniCore-doc/infiniop/ops/causal_softmax/README.md b/InfiniCore-doc/infiniop/ops/causal_softmax/README.md new file mode 100644 index 0000000000000000000000000000000000000000..29180f8f45de66ff08c0ba71dcc426896983857a --- /dev/null +++ b/InfiniCore-doc/infiniop/ops/causal_softmax/README.md @@ -0,0 +1,132 @@ + +# `Causal Softmax` + +`Causal Softmax` 是使用二维因果掩码的 softmax 函数，常用于各类因果类模型。其公式如下： + +$$ y = softmax(x + mask) $$ + +其中 + +$$ softmax(v_i) = \frac{e^{v_i}}{\sum_{k=0}^{N - 1} e^{v_k}} $$ + +对于一个形状为 $(M,N)$ 的二维输入（一般 $M\leq N$），因果掩码定义如下： + +$$ +mask_{i,j} = +\begin{cases} +0 & \text{if } j \leq N - M + i \\ +-\infty & \text{otherwise} +\end{cases} +$$ + +以形状为 $[4, 7]$ 的输入为例，最终计算结果会有如下形式： + +$$ \left[\begin{gathered} + y_{0,0} & y_{0,1} & y_{0, 2} & y_{0, 3} & 0 & 0 & 0\\ + y_{1,0} & y_{1,1} & y_{1, 2} & y_{1, 3} & y_{1, 4} & 0 & 0\\ + y_{2,0} & y_{2,1} & y_{2, 2} & y_{2, 3} & y_{2, 4} & y_{2,5} & 0\\ + y_{3,0} & y_{3,1} & y_{3, 2} & y_{3, 3} & y_{3, 4} & y_{3,5} & y_{3, 6} + \end{gathered}\right] $$ + +### 计算 + +```c +infiniStatus_t infiniopCausalSoftmax( + infiniopCausalSoftmaxDescriptor_t desc, + void *workspace, + size_t workspace_size, + void *y, + const void *x, + void *stream +); +``` +
参数：
+ + - `desc`: 使用 `infiniopCreateCausalSoftmaxDescriptor()` 初始化的算子描述符。 + - `workspace`: 算子计算所需的额外工作空间。 + - `workspace_size`: `workspace` 的大小，单位：字节（byte）。 + - `y`: 计算结果的数据地址。张量限制见[创建算子描述](#创建算子描述)部分。 + - `x`: 输入数据地址，可以与 `y` 相同。张量限制见[创建算子描述](#创建算子描述)部分。 + - `stream`: 计算流/队列。 + +
返回值：
+ + - [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_BAD_PARAM`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`], [`INFINI_STATUS_INTERNAL_ERROR`] + +--- + +### 创建算子描述 + +```c +infiniStatus_t infiniopCreateCausalSoftmaxDescriptor( + infiniopHandle_t handle, + infiniopCausalSoftmaxDescriptor_t *desc_ptr, + infiniopTensorDescriptor_t y_desc, + infiniopTensorDescriptor_t x_desc +); +``` +
参数：
+ + - `handle`: `infiniopHandle_t` 类型的硬件控柄。详情请看：[`InfiniopHandle_t`] + - `desc_ptr`: 存放将被初始化的算子描述符的地址。 + - `y_desc` - { dT | ((batch,) total, seqlen) | ($\ldots,1$) }: + 算子计算参数 `y` 的张量描述，三维或者两维，最后一维连续。 + - `x_desc` - { dT | ((batch,) total, seqlen) | ($\ldots,1$) }: + 算子计算参数 `x` 的张量描述，形状与 `y_desc` 一致，最后一维连续。 + +参数限制： + + - **`dT`**: (`Float16`, `Float32`, `Float64`, `Bfloat16`) 之一 + +
返回值：
+ + - [`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 infiniopGetCausalSoftmaxWorkspaceSize( + infiniopCausalSoftmaxDescriptor_t desc, + size_t *size +); +``` +
参数：
+ + - `desc`: 使用 `infiniopCreateCausalSoftmaxDescriptor()` 初始化的算子描述符。 + - `size`: 存放额外空间大小的计算结果的地址。 + +
返回值：
+ + - [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_BAD_PARAM`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`]. + +--- + +### 销毁算子描述符 + +```c +infiniopStatus_t infiniopDestroyCausalSoftmaxDescriptor( + infiniopCausalSoftmaxDescriptor_t desc +); +``` + +
参数：
+ + - `desc`: 待销毁的算子描述符。 + +
返回值：
+ + - [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`]. + + +[`InfiniopHandle_t`]: /infiniop/handle/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 diff --git a/InfiniCore-doc/infiniop/ops/clip/README.md b/InfiniCore-doc/infiniop/ops/clip/README.md new file mode 100644 index 0000000000000000000000000000000000000000..ede343fe75ddd59abe7cc037a02ed1d42585438b --- /dev/null +++ b/InfiniCore-doc/infiniop/ops/clip/README.md @@ -0,0 +1,153 @@ +# `Clip` + +`Clip`，即**裁剪**算子。用于将输入张量的元素值限制在指定的最小值和最大值范围内。对于超出范围的值，将被裁剪到范围边界。 + +对于输入张量 $x$，以及两个与输入相同形状的张量参数 $minval$和 $maxval$，输出张量 $y$ 中的每个元素按以下规则计算： + +$$ +y_i = \begin{cases} +minval_i & \text{if } x_i < minval_i \\ +maxval_i & \text{if } x_i > maxval_i \\ +x_i & \text{otherwise} +\end{cases} +$$ + +每个元素都会与输入张量的对应元素进行比较。例如，对于输入张量 $x = [-1.5, 0.5, 2.5]$，minval = [-2.0, 0.0, 1.0]，maxval = [0.0, 1.0, 2.0]，输出将是 $y = [-1.5, 0.5, 2.0]$。 + +## 接口 + +### 计算 + +```c +infiniStatus_t infiniopClip( + infiniopClipDescriptor_t desc, + void *workspace, + size_t workspace_size, + void *y, + const void *x, + const void *min_val, + const void *max_val, + void *stream +); +``` + +
参数：
+ +- `desc`: + 已使用 `infiniopCreateClipDescriptor()` 初始化的算子描述符。 +- `workspace`: + 算子执行所需的工作空间。 +- `workspace_size`: + 工作空间大小，以字节为单位。 +- `y`: + 计算输出结果。 +- `x`: + 输入张量。 +- `min_val`: + 裁剪的最小值，必须是与输入张量形状相同的张量。 +- `max_val`: + 裁剪的最大值，必须是与输入张量形状相同的张量。在实现中使用了 `return max(min(x, max_val), min_val)` 的方式，这会导致当 min_val > max_val 时，输出总是等于 min_val。 +- `stream`: + 计算流/队列。 +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`] +- [`INFINI_STATUS_BAD_TENSOR_DTYPE`] +- [`INFINI_STATUS_INSUFFICIENT_WORKSPACE`] +- [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`] + + +### 创建算子描述符 + +```c +infiniStatus_t infiniopCreateClipDescriptor( + infiniopHandle_t handle, + infiniopClipDescriptor_t *desc_ptr, + infiniopTensorDescriptor_t y, + infiniopTensorDescriptor_t x, + infiniopTensorDescriptor_t min_val, + infiniopTensorDescriptor_t max_val +); +``` + +
参数：
+ +- `handle`: + `infiniopHandle_t` 类型的硬件控柄。详情请看：[`InfiniopHandle_t`] +- `desc_ptr`: + `infiniopClipDescriptor_t` 指针，指向将被初始化的算子描述符地址。 +- `y` - {dT | (d1, ..., dn) | (...)} : + 算子输出的张量描述。 +- `x` - {dT | (d1, ..., dn) | (...)} : + 算子输入的张量描述。 +- `min_val` - {dT | (d1, ..., dn) | (...)} : + 裁剪的最小值张量描述，必须是与输入张量形状相同的张量。 +- `max_val` - {dT | (d1, ..., dn) | (...)} : + 裁剪的最大值张量描述，必须是与输入张量形状相同的张量。 + +参数限制： + +- `dT`: (`Float16`, `Float32`, `Float64`, `BFloat16`) 之一。 +- 输入 `a` 与 `b` 的形状需与 `c` 相同。`a` 与 `b` 涉及多向广播时需调整步长以匹配多向广播的映射关系。 +- 支持原位计算，即计算时 `c` 可以和 `a` 或 `b` 指向同一地址。 +- 计算输出参数 `c` 不能进行广播（`c` 的步长不能涉及广播设置，即步长不能有 0） + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`] +- [`INFINI_STATUS_BAD_TENSOR_DTYPE`] +- [`INFINI_STATUS_BAD_TENSOR_SHAPE`] +- [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`] + + + +### 查询工作空间大小 + +```c +infiniStatus_t infiniopGetClipWorkspaceSize( + infiniopClipDescriptor_t desc, + size_t *workspace_size +); +``` + +
参数：
+ +- `desc`: + 输入。已初始化的算子描述符。 +- `workspace_size`: + 输出。算子执行所需的工作空间大小，以字节为单位。 + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`]: 成功获取工作空间大小。 +- [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`]: 当设备类型不受支持时。 + +### 销毁算子描述符 + +```c +infiniStatus_t infiniopDestroyClipDescriptor( + infiniopClipDescriptor_t desc +); +``` + +
参数：
+ +- `desc`: + 输入。待销毁的算子描述符。 + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`] +- [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`] + + + +[`InfiniopHandle_t`]: /infiniop/handle/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_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_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_INSUFFICIENT_WORKSPACE`]: /common/status/README.md#INFINI_STATUS_INSUFFICIENT_WORKSPACE \ No newline at end of file diff --git a/InfiniCore-doc/infiniop/ops/cos/README.md b/InfiniCore-doc/infiniop/ops/cos/README.md new file mode 100644 index 0000000000000000000000000000000000000000..06dc428cef4471b213c2c23b8efd85fb84e33665 --- /dev/null +++ b/InfiniCore-doc/infiniop/ops/cos/README.md @@ -0,0 +1,128 @@ +# `Cos` + +`Cos`, 即**余弦**算子，为单目逐元素算子。其计算可被表述为： + +$$ output = \cos(input) $$ + +其中 `input` 为输入，`output` 为输出。 + +## 接口 + +### 计算 + +```c +infiniStatus_t infiniopCos( + infiniopCosDescriptor_t desc, + void *workspace, + size_t workspace_size, + void *output, + const void *input, + void *stream +); +``` + +
参数：
+ +- `desc`: + 已使用 `infiniopCreateCosDescriptor()` 初始化的算子描述符； +- `workspace`: + 指向算子计算所需的额外工作空间； +- `workspace_size`: + `workspace` 的大小，单位：字节； +- `output`: + 输出张量。张量限制见[创建算子描述](#创建算子描述)部分； +- `input`: + 输入张量。张量限制见[创建算子描述](#创建算子描述)部分； +- `stream`: + 计算流/队列； + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_BAD_PARAM`], [`INFINI_STATUS_INSUFFICIENT_WORKSPACE`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`], [`INFINI_STATUS_INTERNAL_ERROR`]，[`INFINI_STATUS_BAD_TENSOR_DTYPE`]. + +### 创建算子描述 + +```c +infiniStatus_t infiniopCreateCosDescriptor( + infiniopHandle_t handle, + infiniopCosDescriptor_t *desc_ptr, + infiniopTensorDescriptor_t output, + infiniopTensorDescriptor_t input +); +``` + +
参数：
+ +- `handle`: + `infiniopHandle_t` 类型的硬件控柄。详情请看：[`InfiniopHandle_t`]。 +- `desc_ptr`: + `infiniopCosDescriptor_t` 指针，指向将被初始化的算子描述符地址； +- `output` - { dT | (d1,...,dn) | (...) }: + 算子计算参数 `output` 的张量描述，支持原位计算。 +- `input` - { dT | (d1,...,dn) | (...) }: + 算子计算参数 `input` 的张量描述，支持原位计算。 + +参数限制： + +- `dT`: (`Float16`, `Float32`, `BFloat16`) 之一。 +- 输入 `input` 与输出 `output` 的形状需相同。 +- 支持原位计算，即计算时 `output` 可以和 `input` 指向同一地址。 +- 输入输出类型一致。 + +
返回值：
+ +- [`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 infiniopGetCosWorkspaceSize( + infiniopCosDescriptor_t desc, + size_t *size +); +``` + +
参数：
+ +- `desc`: + 已使用 `infiniopCreateCosDescriptor()` 初始化的算子描述符； +- `size`: + 额外空间大小的计算结果的写入地址； + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_NULL_POINTER`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`]. + +### 销毁算子描述符 + +```c +infiniStatus_t infiniopDestroyCosDescriptor( + infiniopCosDescriptor_t desc +); +``` + +
参数：
+ +- `desc`: + 输入。 待销毁的算子描述符； + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`]. + +## 已知问题 + +无 + + +[`InfiniopHandle_t`]: /infiniop/handle/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_NULL_POINTER`]: /common/status/README.md#INFINI_STATUS_NULL_POINTER +[`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 \ No newline at end of file diff --git a/InfiniCore-doc/infiniop/ops/exp/README.md b/InfiniCore-doc/infiniop/ops/exp/README.md new file mode 100644 index 0000000000000000000000000000000000000000..92d558867675039a8dc4d981f03ac6bbd3eb0ac2 --- /dev/null +++ b/InfiniCore-doc/infiniop/ops/exp/README.md @@ -0,0 +1,128 @@ +# `Exp` + +`Exp`, 即**指数**算子，为单目逐元素算子。其计算可被表述为： + +$$ output = e^{input} $$ + +其中 `input` 为输入，`output` 为输出。 + +## 接口 + +### 计算 + +```c +infiniStatus_t infiniopExp( + infiniopExpDescriptor_t desc, + void *workspace, + size_t workspace_size, + void *output, + const void *input, + void *stream +); +``` + +
参数：
+ +- `desc`: + 已使用 `infiniopCreateExpDescriptor()` 初始化的算子描述符； +- `workspace`: + 指向算子计算所需的额外工作空间； +- `workspace_size`: + `workspace` 的大小，单位：字节； +- `output`: + 输出张量。张量限制见[创建算子描述](#创建算子描述)部分； +- `input`: + 输入张量。张量限制见[创建算子描述](#创建算子描述)部分； +- `stream`: + 计算流/队列； + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_BAD_PARAM`], [`INFINI_STATUS_INSUFFICIENT_WORKSPACE`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`], [`INFINI_STATUS_INTERNAL_ERROR`]，[`INFINI_STATUS_BAD_TENSOR_DTYPE`]. + +### 创建算子描述 + +```c +infiniStatus_t infiniopCreateExpDescriptor( + infiniopHandle_t handle, + infiniopExpDescriptor_t *desc_ptr, + infiniopTensorDescriptor_t output, + infiniopTensorDescriptor_t input +); +``` + +
参数：
+ +- `handle`: + `infiniopHandle_t` 类型的硬件控柄。详情请看：[`InfiniopHandle_t`]。 +- `desc_ptr`: + `infiniopExpDescriptor_t` 指针，指向将被初始化的算子描述符地址； +- `output` - { dT | (d1,...,dn) | (...) }: + 算子计算参数 `output` 的张量描述，支持原位计算。 +- `input` - { dT | (d1,...,dn) | (...) }: + 算子计算参数 `input` 的张量描述，支持原位计算。 + +参数限制： + +- `dT`: (`Float16`, `Float32`, `BFloat16`) 之一。 +- 输入 `input` 与输出 `output` 的形状需相同。 +- 支持原位计算，即计算时 `output` 可以和 `input` 指向同一地址。 +- 输入输出类型一致。 + +
返回值：
+ +- [`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 infiniopGetExpWorkspaceSize( + infiniopExpDescriptor_t desc, + size_t *size +); +``` + +
参数：
+ +- `desc`: + 已使用 `infiniopCreateExpDescriptor()` 初始化的算子描述符； +- `size`: + 额外空间大小的计算结果的写入地址； + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_NULL_POINTER`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`]. + +### 销毁算子描述符 + +```c +infiniStatus_t infiniopDestroyExpDescriptor( + infiniopExpDescriptor_t desc +); +``` + +
参数：
+ +- `desc`: + 输入。 待销毁的算子描述符； + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`]. + +## 已知问题 + +无 + + +[`InfiniopHandle_t`]: /infiniop/handle/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_NULL_POINTER`]: /common/status/README.md#INFINI_STATUS_NULL_POINTER +[`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 \ No newline at end of file diff --git a/InfiniCore-doc/infiniop/ops/gemm/README.md b/InfiniCore-doc/infiniop/ops/gemm/README.md new file mode 100644 index 0000000000000000000000000000000000000000..4c43f8144cd655e7364f3876ed8f4a326cecbc67 --- /dev/null +++ b/InfiniCore-doc/infiniop/ops/gemm/README.md @@ -0,0 +1,144 @@ + +# `GEMM` + +`GEMM`，即**通用矩阵乘法**算子。计算公式为： + +$$ C = α ⋅ (A * B) + β ⋅ C $$ + +其中： + +- `A` 为左输入张量，形状为 `( [batch,] M, K )`。 +- `B` 为右输入张量，形状为 `( [batch,] K, N )`。 +- `C` 的形状由矩阵乘法规则确定，形状为 `( [batch,] M, N )`。 +- `α` 为缩放因子，`β` 为累加系数； + +## 接口 + +### 计算 + +```c +infiniStatus_t infiniopGemm( + infiniopGemmDescriptor_t desc, + void *workspace, + size_t workspace_size, + void *c, + const void *a, + const void *b, + void *stream +); +``` + +
参数：
+ +- `desc`: + 已使用 `infiniopCreateGemmDescriptor()` 初始化的算子描述符。 +- `workspace`: + 指向算子计算所需的额外工作空间。 +- `workspace_size`: + `workspace` 的大小，单位：字节。 +- `c`: + 计算输出结果。张量限制见[创建算子描述](#创建算子描述)部分。 +- `a`: + 左输入张量。张量限制见[创建算子描述](#创建算子描述)部分。 +- `b`: + 右输入张量。张量限制见[创建算子描述](#创建算子描述)部分。 +- `stream`: + 计算流/队列。 + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_BAD_PARAM`], [`INFINI_STATUS_INSUFFICIENT_WORKSPACE`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`], [`INFINI_STATUS_INTERNAL_ERROR`]. + +### 创建算子描述 + +```c +infiniStatus_t infiniopCreateGemmDescriptor( + infiniopHandle_t handle, + infiniopGemmDescriptor_t *desc_ptr, + infiniopTensorDescriptor_t c_desc, + infiniopTensorDescriptor_t a_desc, + infiniopTensorDescriptor_t b_desc, + float alpha, + float beta +); +``` + +
参数：
+ +- `handle`:、 + `infiniopHandle_t` 类型的硬件控柄。详情请看：[`InfiniopHandle_t`] +- `desc_ptr`: + 指向将被初始化的算子描述符地址； +- `c_desc` - { dT | ( [batch,] , M, N) | (~) }: + 算子计算参数 `c` 的张量描述。 +- `a_desc` - { dT | ( [batch,] , M, K) | (~) }: + 算子计算参数 `a` 的张量描述。 +- `b_desc` - { dT | ( [batch,] , K, N) | (~) }: + 算子计算参数 `b` 的张量描述。 +- `alpha` - float: + 算子计算缩放因子。 +- `beta` - float: + 算子计算累加系数。 + +
参数限制：
+ +参数限制： + +- `dT`: (`Float16`, `Float32`, `BFloat16`) 之一； +- `[batch,]`: `batch ≥ 1`（可选）； +- `M`: M > 0； +- `N`: N > 0； +- `K`: K > 0； + +
返回值：
+ +- [`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 infiniopGetGemmWorkspaceSize( + infiniopGemmDescriptor_t desc, + size_t *size +); +``` + +
参数：
+ +- `desc`: + 已使用 `infiniopCreateMatmulDescriptor()` 初始化的算子描述符。 +- `size`: + 额外空间大小的计算结果的写入地址； + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_BAD_PARAM`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`]. + +### 销毁算子描述符 + +```c +infiniStatus_t infiniopDestroyGemmDescriptor( + infiniopGemmDescriptor_t desc +); +``` + +
参数：
+ +- `desc`: + 输入。待销毁的算子描述符； + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`]. + + +[`InfiniopHandle_t`]: /infiniop/handle/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 diff --git a/InfiniCore-doc/infiniop/ops/hardswish/README.md b/InfiniCore-doc/infiniop/ops/hardswish/README.md new file mode 100644 index 0000000000000000000000000000000000000000..046c9ba02fd488de9f7bc1609d624a33f68cf2cc --- /dev/null +++ b/InfiniCore-doc/infiniop/ops/hardswish/README.md @@ -0,0 +1,128 @@ +# `HardSwish` + +`HardSwish`, 即**硬Swish**算子，为单目逐元素算子。其计算可被表述为： + +$$ output = input \times \frac{\text{ReLU6}(input + 3)}{6} $$ + +其中 `input` 为输入，`output` 为输出，$\text{ReLU6}(x) = \min(\max(0, x), 6)$。 + +## 接口 + +### 计算 + +```c +infiniStatus_t infiniopHardSwish( + infiniopHardSwishDescriptor_t desc, + void *workspace, + size_t workspace_size, + void *output, + const void *input, + void *stream +); +``` + +
参数：
+ +- `desc`: + 已使用 `infiniopCreateHardSwishDescriptor()` 初始化的算子描述符； +- `workspace`: + 指向算子计算所需的额外工作空间； +- `workspace_size`: + `workspace` 的大小，单位：字节； +- `output`: + 输出张量。张量限制见[创建算子描述](#创建算子描述)部分； +- `input`: + 输入张量。张量限制见[创建算子描述](#创建算子描述)部分； +- `stream`: + 计算流/队列； + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_BAD_PARAM`], [`INFINI_STATUS_INSUFFICIENT_WORKSPACE`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`], [`INFINI_STATUS_INTERNAL_ERROR`]，[`INFINI_STATUS_BAD_TENSOR_DTYPE`]. + +### 创建算子描述 + +```c +infiniStatus_t infiniopCreateHardSwishDescriptor( + infiniopHandle_t handle, + infiniopHardSwishDescriptor_t *desc_ptr, + infiniopTensorDescriptor_t output, + infiniopTensorDescriptor_t input +); +``` + +
参数：
+ +- `handle`: + `infiniopHandle_t` 类型的硬件控柄。详情请看：[`InfiniopHandle_t`]。 +- `desc_ptr`: + `infiniopHardSwishDescriptor_t` 指针，指向将被初始化的算子描述符地址； +- `output` - { dT | (d1,...,dn) | (...) }: + 算子计算参数 `output` 的张量描述，支持原位计算。 +- `input` - { dT | (d1,...,dn) | (...) }: + 算子计算参数 `input` 的张量描述，支持原位计算。 + +参数限制： + +- `dT`: (`Float16`, `Float32`, `BFloat16`) 之一。 +- 输入 `input` 与输出 `output` 的形状需相同。 +- 支持原位计算，即计算时 `output` 可以和 `input` 指向同一地址。 +- 输入输出类型一致。 + +
返回值：
+ +- [`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 infiniopGetHardSwishWorkspaceSize( + infiniopHardSwishDescriptor_t desc, + size_t *size +); +``` + +
参数：
+ +- `desc`: + 已使用 `infiniopCreateHardSwishDescriptor()` 初始化的算子描述符； +- `size`: + 额外空间大小的计算结果的写入地址； + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_NULL_POINTER`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`]. + +### 销毁算子描述符 + +```c +infiniStatus_t infiniopDestroyHardSwishDescriptor( + infiniopHardSwishDescriptor_t desc +); +``` + +
参数：
+ +- `desc`: + 输入。 待销毁的算子描述符； + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`]. + +## 已知问题 + +无 + + +[`InfiniopHandle_t`]: /infiniop/handle/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_NULL_POINTER`]: /common/status/README.md#INFINI_STATUS_NULL_POINTER +[`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 \ No newline at end of file diff --git a/InfiniCore-doc/infiniop/ops/leaky_relu/README.md b/InfiniCore-doc/infiniop/ops/leaky_relu/README.md new file mode 100644 index 0000000000000000000000000000000000000000..754eac9db34f8f69f629098ac25ede8911178439 --- /dev/null +++ b/InfiniCore-doc/infiniop/ops/leaky_relu/README.md @@ -0,0 +1,132 @@ +# `LeakyReLU` + +`LeakyReLU`, 即**带泄漏的线性整流单元**算子，为单目逐元素算子。其计算可被表述为： + +$$ output = \max(0, input) + negative\_slope \times \min(0, input) $$ + +其中 `input` 为输入，`output` 为输出，`negative_slope` 为负斜率参数。 + +## 接口 + +### 计算 + +```c +infiniStatus_t infiniopLeakyReLU( + infiniopLeakyReLUDescriptor_t desc, + void *workspace, + size_t workspace_size, + void *output, + const void *input, + void *stream +); +``` + +
参数：
+ +- `desc`: + 已使用 `infiniopCreateLeakyReLUDescriptor()` 初始化的算子描述符； +- `workspace`: + 指向算子计算所需的额外工作空间； +- `workspace_size`: + `workspace` 的大小，单位：字节； +- `output`: + 输出张量。张量限制见[创建算子描述](#创建算子描述)部分； +- `input`: + 输入张量。张量限制见[创建算子描述](#创建算子描述)部分； +- `stream`: + 计算流/队列； + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_BAD_PARAM`], [`INFINI_STATUS_INSUFFICIENT_WORKSPACE`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`], [`INFINI_STATUS_INTERNAL_ERROR`]，[`INFINI_STATUS_BAD_TENSOR_DTYPE`]. + +### 创建算子描述 + +```c +infiniStatus_t infiniopCreateLeakyReLUDescriptor( + infiniopHandle_t handle, + infiniopLeakyReLUDescriptor_t *desc_ptr, + infiniopTensorDescriptor_t output, + infiniopTensorDescriptor_t input, + float negative_slope +); +``` + +
参数：
+ +- `handle`: + `infiniopHandle_t` 类型的硬件控柄。详情请看：[`InfiniopHandle_t`]。 +- `desc_ptr`: + `infiniopLeakyReLUDescriptor_t` 指针，指向将被初始化的算子描述符地址； +- `output` - { dT | (d1,...,dn) | (...) }: + 算子计算参数 `output` 的张量描述，支持原位计算。 +- `input` - { dT | (d1,...,dn) | (...) }: + 算子计算参数 `input` 的张量描述，支持原位计算。 +- `negative_slope`: + 负斜率参数，用于控制负值部分的斜率。 + +参数限制： + +- `dT`: (`Float16`, `Float32`, `BFloat16`) 之一。 +- 输入 `input` 与输出 `output` 的形状需相同。 +- 支持原位计算，即计算时 `output` 可以和 `input` 指向同一地址。 +- 输入输出类型一致。 +- `negative_slope` 通常为小的正数，默认值为 0.01。 + +
返回值：
+ +- [`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 infiniopGetLeakyReLUWorkspaceSize( + infiniopLeakyReLUDescriptor_t desc, + size_t *size +); +``` + +
参数：
+ +- `desc`: + 已使用 `infiniopCreateLeakyReLUDescriptor()` 初始化的算子描述符； +- `size`: + 额外空间大小的计算结果的写入地址； + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_NULL_POINTER`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`]. + +### 销毁算子描述符 + +```c +infiniStatus_t infiniopDestroyLeakyReLUDescriptor( + infiniopLeakyReLUDescriptor_t desc +); +``` + +
参数：
+ +- `desc`: + 输入。 待销毁的算子描述符； + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`]. + +## 已知问题 + +无 + + +[`InfiniopHandle_t`]: /infiniop/handle/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_NULL_POINTER`]: /common/status/README.md#INFINI_STATUS_NULL_POINTER +[`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 \ No newline at end of file diff --git a/InfiniCore-doc/infiniop/ops/mul/README.md b/InfiniCore-doc/infiniop/ops/mul/README.md new file mode 100644 index 0000000000000000000000000000000000000000..38f54a7af91198457e39d67c0327d7b6555a5804 --- /dev/null +++ b/InfiniCore-doc/infiniop/ops/mul/README.md @@ -0,0 +1,134 @@ +# `Mul` + +`Mul`, 即**乘法**算子，为双目逐元素算子。其计算可被表述为： + +$$ c = a * b $$ + +其中 `a` 和 `b` 为输入，`c` 为输出。 + +## 接口 + +### 计算 + +```c +infiniStatus_t infiniopMul( + infiniopMulDescriptor_t desc, + void *workspace, + size_t workspace_size, + void *c, + const void *a, + const void *b, + void *stream +); +``` + +
参数：
+ +- `desc`: + 已使用 `infiniopCreateMulDescriptor()` 初始化的算子描述符； +- `workspace`: + 指向算子计算所需的额外工作空间； +- `workspace_size`: + `workspace` 的大小，单位：字节； +- `c`: + 输出张量。张量限制见创建算子描述部分； +- `a`: + 输入张量。张量限制见创建算子描述部分； +- `b`: + 输入张量。张量限制见创建算子描述部分； +- `stream`: + 计算流/队列； + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_BAD_PARAM`], [`INFINI_STATUS_INSUFFICIENT_WORKSPACE`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`], [`INFINI_STATUS_INTERNAL_ERROR`]，[`INFINI_STATUS_BAD_TENSOR_DTYPE`]. + +### 创建算子描述 + +```c +infiniStatus_t infiniopCreateMulDescriptor( + infiniopHandle_t handle, + infiniopMulDescriptor_t *desc_ptr, + infiniopTensorDescriptor_t c_desc, + infiniopTensorDescriptor_t a_desc, + infiniopTensorDescriptor_t b_desc +); +``` + +
参数：
+ +- `handle`: + `infiniopHandle_t` 类型的硬件控柄。详情请看：[`InfiniopHandle_t`]。 +- `desc_ptr`: + `infiniopMulDescriptor_t` 指针，指向将被初始化的算子描述符地址； +- `c_desc` - { dT | (d1,...,dn) | (...) }: + 算子计算参数 `c` 的张量描述，支持原位计算。 +- `a_desc` - { dT | (d1,...,dn) | (...) }: + 算子计算参数 `a` 的张量描述，支持原位计算，支持多向广播。 +- `b_desc` - { dT | (d1,...,dn) | (...) }: + 算子计算参数 `b` 的张量描述，支持原位计算，支持多向广播。 + +参数限制： + +- `dT`: (`Float16`, `Float32`, `Float64`, `BFloat16`) 之一。 +- 输入 `a` 与 `b` 的形状需与 `c` 相同。`a` 与 `b` 涉及多向广播时需调整步长以匹配多向广播的映射关系。 +- 支持原位计算，即计算时 `c` 可以和 `a` 或 `b` 指向同一地址。 +- 计算输出参数 `c` 不能进行广播（`c` 的步长不能涉及广播设置，即步长不能有 0） + +
返回值：
+ +- [`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 infiniopGetMulWorkspaceSize( + infiniopMulDescriptor_t desc, + size_t *size +); +``` + +
参数：
+ +- `desc`: + 已使用 `infiniopCreateMulDescriptor()` 初始化的算子描述符； +- `size`: + 额外空间大小的计算结果的写入地址； + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_NULL_POINTER`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`]. + +### 销毁算子描述符 + +```c +infiniStatus_t infiniopDestroyMulDescriptor( + infiniopMulDescriptor_t desc +); +``` + +
参数：
+ +- `desc`: + 输入。 待销毁的算子描述符； + +
返回值：
+ +- [`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_NULL_POINTER`]: /common/status/README.md#INFINI_STATUS_NULL_POINTER +[`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 \ No newline at end of file diff --git a/InfiniCore-doc/infiniop/ops/random_sample/README.md b/InfiniCore-doc/infiniop/ops/random_sample/README.md new file mode 100644 index 0000000000000000000000000000000000000000..77add7a439ab2295c352c7b23490402202be9e12 --- /dev/null +++ b/InfiniCore-doc/infiniop/ops/random_sample/README.md @@ -0,0 +1,159 @@ + +# `Random Sample` + +`Random Sample`, 即**随机采样**算子：给定一个代表离散概率分布（或权重）的序列： + +$$ P = \{ p_0, p_1, \dots, p_{n-1} \}, \quad \sum_{i=0}^{n-1} p_i = 1 $$ + +以及一个随机数种子 $r$ 服从均匀分布： + +$$ r \sim U(0,1) $$ + +从分布中采样出一个样本，样本为0到概率分布总长度减1之间的一个整数。支持 top-k、top-p 采样策略，支持temperature 随机性调整。温度缩放 (Temperature Scaling) 给定原始概率分布 $P$ 和 `temperature` 参数 $T$，调整后的概率分布 $P'$ 为： + +$$ P^{\prime} = \{ p_0^{\prime}, p_1^{\prime}, \dots, p_{n-1}^{\prime} \}, \quad p_i^{\prime} = \frac{e^{\frac{p_i}{T}}}{\sum_{j=0}^{n-1} e^{\frac{p_j}{T}}} $$ + +其中 + +- $p_i$ 是第 $i$ 个元素的原始概率； +- Top-k 选择概率最高的前 `k`。 +- Top-p 选择累计概率和达到设定阈值 `p` 的最小子集； + +## 接口 + +### 计算 + +```c +infiniStatus_t infiniopRandomSample( + infiniopRandomSampleDescriptor_t desc, + void *workspace, + size_t workspace_size, + void *result, + void const *probs, + float random_val, + float topp, + uint64_t topk, + float temperature, + void *stream +); +``` + +
参数：
+ +- `desc`: + 已使用 `infiniopCreateRandomSampleDescriptor()` 初始化的算子描述符； +- `workspace`: + 指向算子计算所需的额外工作空间； +- `workspace_size`: + `workspace` 的大小，单位：字节； +- `result`: + 采样输出结果。张量限制见[创建算子描述](#创建算子描述)部分； +- `probs`: + 概率分布数据。张量限制见[创建算子描述](#创建算子描述)部分； +- `random_val`: + 随机数种子，一般通过 Uniform 分布产生，范围是 $[0,1]$。 +- `topp`: + top-p 采样阈值，使得采样只从靠前的概率和为 `topp` 的范围内进行，范围是 $[0,1]$。当 `topp` 为0时，采样退化为 **Argmax** 算子。当 `topp` 大于等于1时，不设置 top-p 阈值； +- `topk`: + top-k 采样阈值，使得采样只从靠前的 `topk` 项里进行，范围是 $[0,\infty)$。当 `topk` 为1时，采样退化为 **Argmax** 算子；当 `topk` 大于等于概率分布长度或为0时，不设置 top-k 阈值； +- `temperature`: + 概率分布随机度，范围是 $[0,\infty)$。 + - 当 `temperature` 为1时，采样结果与原始概率分布一致； + - 当 `temperature` 大于1时，采样结果越靠近原始概率分布，越可能被选中； + - 当 `temperature` 小于1时，采样结果越远离原始概率分布，越可能被选中； + - 当 `temperature` 为0时，采样退化为 [`Argmax`] 算子； +- `stream`: + 计算流/队列； + +
返回值：
+ +- 当 `random_val`、`topp`、`topk`、或 `temperature` 超出范围返回 [`INFINI_STATUS_BAD_PARAM`]。 +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_BAD_PARAM`], [`INFINI_STATUS_INSUFFICIENT_WORKSPACE`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`], [`INFINI_STATUS_INTERNAL_ERROR`]. + +### 创建算子描述 + +```c +infiniStatus_t infiniopCreateRandomSampleDescriptor( + infiniopHandle_t handle, + infiniopRandomSampleDescriptor_t *desc_ptr, + infiniopTensorDescriptor_t result, + infiniopTensorDescriptor_t probs +); +``` + +
参数：
+ +- `handle`: + `infiniopHandle_t` 类型的硬件控柄。详情请看：[`InfiniopHandle_t`]。 +- `desc_ptr`: + `infiniopRandomSampleDescriptor_t` 指针，指向将被初始化的算子描述符地址； +- `result` - ${ dOut | (,) | (,) }$: + 算子计算参数 `result` 的张量描述； +- `probs` - ${ dT | (N,) | (1,) }$: + 算子计算参数 `probs` 的张量描述。目前仅支持连续一维张量； + +参数限制： + +- `dT`: (`Float16`, `Float32`, `BFloat16`) 之一。 +- `dOut`: `Uint64`。 +- `N`: N > 0； + +
返回值：
+ +- [`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 infiniopGetRandomSampleWorkspaceSize( + infiniopRandomSampleDescriptor_t desc, + size_t *size +); +``` + +
参数：
+ +- `desc`: + 已使用 `infiniopCreateRandomSampleDescriptor()` 初始化的算子描述符； +- `size`: + 额外空间大小的计算结果的写入地址； + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_BAD_PARAM`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`]. + +### 销毁算子描述符 + +```c +infiniStatus_t infiniopDestroyRandomSampleDescriptor( + infiniopRandomSampleDescriptor_t desc +); +``` + +
参数：
+ +- `desc`: + 输入。 待销毁的算子描述符； + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`]. + +## 已知问题 + +### 平台限制 + +- 昇腾目前只支持 [`Argmax`] 的情况； + + +[`Argmax`]: / +[`InfiniopHandle_t`]: /infiniop/handle/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 diff --git a/InfiniCore-doc/infiniop/ops/rearrange/README.md b/InfiniCore-doc/infiniop/ops/rearrange/README.md new file mode 100644 index 0000000000000000000000000000000000000000..bf553765badd46f5385e734c2bcf27fb201c37b4 --- /dev/null +++ b/InfiniCore-doc/infiniop/ops/rearrange/README.md @@ -0,0 +1,160 @@ + +# `Rearrange` + +`Rearrange`，即**布局重整**算子。用于在数据类型和形状相同、布局可能不同的张量之间拷贝数据。 + +`Rearrange` 算子关心 2 个张量，称为 `src` 和 `dst`，它们的数据类型和形状相同，但布局可能不同。由于两个张量形状相同，二者的数据元素是一一对应的。算子将 `src` 中的数据拷贝到 `dst` 中的对应位置。 + +例如，要转置 $2 \times 3$ 矩阵： + +> - 符号表示数据元素。 +> - 下标表示数据在存储空间中的位置。 + +$$ +src: +\left( + \begin{gathered} + a_0, b_1, c_2\\ + d_3, e_4, f_5\\ + \end{gathered} +\right) +\stackrel{T}{\rightarrow} +dst: +\left( + \begin{gathered} + a_0, d_1\\ + b_2, e_3\\ + c_4, f_5\\ + \end{gathered} +\right) +$$ + +这个操作可以通过**张量布局变换**和**数据重整** 2 步完成： + +$$ +src: +\left( + \begin{gathered} + a_0, b_1, c_2\\ + d_3, e_4, f_5\\ + \end{gathered} +\right) +\stackrel{T_{meta}}{\rightarrow} +\left( + \begin{gathered} + a_0, d_3\\ + b_1, e_4\\ + c_2, f_5\\ + \end{gathered} +\right) +\stackrel{R}{\rightarrow} +dst: +\left( + \begin{gathered} + a_0, d_1\\ + b_2, e_3\\ + c_4, f_5\\ + \end{gathered} +\right) +$$ + +| 操作 | 解释 +|:-:|:- +| $T$ | 转置，既转置形状布局，也移动数据位置 +| $T_{meta}$ | 不改变数据在存储空间中的排布，但将形状从 $2 \times 3$ 改为 $3 \times 2$，步长从 $1,3$ 改为 $3,1$ +| $R$ | 调用算子 $rearrange(shape=(3,2), strides_{dst}=(1,2),strides_{src}=(3,1))$ + +## 接口 + +### 计算 + +```c +infiniStatus_t infiniopRearrange( + infiniopRearrangeDescriptor_t desc, + void *dst, + const void *src, + void *stream +); +``` + +
参数：
+ +- `desc`: + 已使用 `infiniopCreateRearrangeDescriptor()` 初始化的算子描述符。 +- `dst`: + 计算输出结果。 +- `src`: + 输入张量。 +- `stream`: + 计算流/队列。 + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_BAD_PARAM`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`], [`INFINI_STATUS_INTERNAL_ERROR`]. + +### 创建算子描述 + +```c +infiniStatus_t infiniopCreateRearrangeDescriptor( + infiniopHandle_t handle, + infiniopRearrangeDescriptor_t *desc_ptr, + infiniopTensorDescriptor_t dst_desc, + infiniopTensorDescriptor_t src_desc +); +``` + +
参数：
+ +- `handle`: + `infiniopHandle_t` 类型的硬件控柄。详情请看：[`InfiniopHandle_t`] +- `desc_ptr`: + `infiniopCreateRearrangeDescriptor` 指针，指向将被初始化的算子描述符地址。 +- `dst_desc` - $\{ dT | shape | strides_{dst} \}$: + 算子输出 `dst` 的张量描述。 +- `src_desc` - $\{ dT | shape | strides_{src} \}$: + 算子计算参数 `src` 的张量描述。 + +
参数限制：
+ +参数限制： + +- $dT$: 任意类型。 +- $shape$: 任意形状。 +- $strides_{dst}$: 任意布局，但长度不为 1 的维度不能含有 0 步长（广播）。 +- $strides_{src}$: 任意布局。 + +
返回值：
+ +- [`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 infiniopDestroyRearrangeDescriptor( + infiniopRearrangeDescriptor_t desc +); +``` + +
参数：
+ +- `desc`: + 输入。待销毁的算子描述符。 + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`]. + +## 已知问题 + +无 + + +[`InfiniopHandle_t`]: /infiniop/handle/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_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 diff --git a/InfiniCore-doc/infiniop/ops/rms_norm/README.md b/InfiniCore-doc/infiniop/ops/rms_norm/README.md new file mode 100644 index 0000000000000000000000000000000000000000..8d0c428b8d779bea23e24117affe494f6639ddc3 --- /dev/null +++ b/InfiniCore-doc/infiniop/ops/rms_norm/README.md @@ -0,0 +1,141 @@ +# `RMS Norm` + +`RMS Norm`，即 **Root Mean Square Normalization** 算子，用于对输入张量进行归一化处理。它通过计算输入张量在指定维度上的均方根值（Root Mean Square, RMS），并将其缩放到单位范数。该算子广泛应用于神经网络中，尤其是在处理具有不同尺度的输入数据时。 + +对于输入张量 $X$ 和归一化维度 $D$，RMS Norm 的计算公式为： + +$$ +Y = \frac{X \cdot W}{\sqrt{\frac{1}{N} \sum_{i=1}^{N} X_i^2 + \epsilon}} +$$ + +其中： + +- $N$ 是在归一化维度 $D$ 上的元素数量; +- $\epsilon$ 是一个小的常数，用于避免除以零，通常取值为 $10^{-6}$ 或 $10^{-8}$; +- $W$ 是可选的权重张量，用于对归一化后的结果进行缩放; +- $Y$ 表示归一化后的输出结果; + +## 接口 + +### 计算 + +```c +infiniStatus_t infiniopRMSNorm( + infiniopRMSNormDescriptor_t desc, + void *workspace, + size_t workspace_size, + void *y, + const void *x, + const void *w, + void *stream +); +``` + +
参数：
+ +- `desc`: + 使用 `infiniopCreateRMSNormDescriptor()` 初始化的算子描述符。 +- `workspace`: + 算子计算所需的额外工作空间。 +- `workspace_size`: + `workspace` 的大小，单位：字节。 +- `y`: + 计算结果地址。张量限制见[创建算子描述](#创建算子描述)部分。 +- `x`: + 输入数据地址。张量限制见[创建算子描述](#创建算子描述)部分。 +- `w`: + 权重数据地址（可选）。如果权重张量为 `NULL`，则不进行缩放。 +- `stream`: + 计算流/队列。 + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_BAD_PARAM`], [`INFINI_STATUS_INSUFFICIENT_WORKSPACE`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`], [`INFINI_STATUS_INTERNAL_ERROR`]. + +- 当 `epsilon` 超出范围时返回 [`INFINI_STATUS_BAD_PARAM`]。 + +### 创建算子描述 + +```c +infiniStatus_t infiniopCreateRMSNormDescriptor( + infiniopHandle_t handle, + infiniopRMSNormDescriptor_t *desc_ptr, + infiniopTensorDescriptor_t y_desc, + infiniopTensorDescriptor_t x_desc, + infiniopTensorDescriptor_t w_desc, + float epsilon +); +``` + +
参数：
+ +- `handle`: + 硬件控柄。详情请看：[`InfiniopHandle_t`]。 +- `desc_ptr`: + 存放将被初始化的算子描述符地址。 +- `y_desc` - { dT | (b, d) | (..., 1) }: + 计算结果 `y` 的张量描述。 +- `x_desc` - { dT | (b, d) | (..., 1) }: + 输入 `x` 的张量描述，形状和 `y_desc` 保持一致。 +- `w_desc` - { dW | (d,) | (1,) }: + 权重 `w` 的张量描述。`w_desc` 为一维张量，长度和归一化维度的长度保持一致。如果权重张量为 `NULL`，则不进行缩放。 +- `epsilon` - float: + 用于避免除以零的小常数，范围是 $(0, 1]$。 + +参数限制： + +- `dT`: (`Float16`, `Float32`, `BFloat16`) 之一。 +- `dW`: 与 `dT` 相同，或为 `Float32`。 + +
返回值：
+ +- [`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 infiniopGetRMSNormWorkspaceSize( + infiniopRMSNormDescriptor_t desc, + size_t *size +); +``` + +
参数：
+ +- `desc`: + 使用 `infiniopCreateRMSNormDescriptor()` 初始化的算子描述符。 +- `size`: + 存放空间大小的计算结果的地址。 + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_BAD_PARAM`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`]. + +### 销毁算子描述符 + +```c +infiniStatus_t infiniopDestroyRMSNormDescriptor( + infiniopRMSNormDescriptor_t desc +); +``` + +
参数：
+ +- `desc`: + 待销毁的算子描述符。 + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`]. + + +[`InfiniopHandle_t`]: /infiniop/handle/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 diff --git a/InfiniCore-doc/infiniop/ops/rope/README.md b/InfiniCore-doc/infiniop/ops/rope/README.md new file mode 100644 index 0000000000000000000000000000000000000000..36f9a2803d3c9ed8364fb80c33787d821b6d8b34 --- /dev/null +++ b/InfiniCore-doc/infiniop/ops/rope/README.md @@ -0,0 +1,163 @@ + +# `RoPE` + +`RoPE (Rotary Position Embedding)`, 即**旋转位置编码**算子。 + +对于一个位置为 $m$ 的 token 的嵌入向量 $x$ 中的每两个相邻元素，即第 $2i$ 和 $2i+1$ 个元素，其旋转后的嵌入向量 $y$ 可以表示为： + + $$ + y[2i] = x[2i] \cdot \cos(m\cdot \theta_i) - x[2i+1] \cdot \sin(m\cdot \theta_i) + $$ + $$ + y[2i+1] = x[2i] \cdot \sin(m\cdot \theta_i) + x[2i+1] \cdot \cos(m\cdot \theta_i) + $$ + +其中： + +$$ +\theta_{i} = \text{base}^{\frac{-2i}{d}} +$$ + +- `base`：控制旋转速率的超参数，常用 `base` = 10000。 +- `d` ：嵌入向量长度，须为2的倍数。 +- `i`：嵌入维度的双步长索引，满足 $i \in [0, ..., d/2 - 1]$。 +- `m`：位置 + +公式中的正弦和余弦值 ( $\sin(m\cdot \theta_i)$ 和 $\cos(m\cdot \theta_i)$ ) 只与位置 `m` 和向量长度 `d` 有关，而与嵌入向量的数值无关。本接口支持用户以数表的形式传入正弦和余弦值，避免冗余计算。 + +## 接口 + +### 计算 + +```c +infiniStatus_t infiniopRoPE( + infiniopRoPEDescriptor_t desc, + void *workspace, + size_t workspace_size, + void *y, + const void *x, + const void *pos_ids, + const void *sin_table, + const void *cos_table, + void *stream +); +``` + +
参数：
+ +- `desc`: + 已使用 `infiniopCreateRoPEDescriptor()` 初始化的算子描述符。 +- `workspace`: + 额外工作空间。 +- `workspace_size`: + `workspace` 的大小，单位：字节。 +- `y`: + 计算结果地址，当与 `x` 相同时为原地操作。 +- `x`: + 嵌入向量矩阵（比如自注意力层中的 query 或 key）的数据指针，可与 `y` 相同。 +- `pos_ids`: + 位置数值的地址，代表 `x` 中每个向量对应的 cos、sin 表中的序号。计算时，会根据序号选择表中的数值进行位置编码。用户应自行保证序号不会超过 cos、sin 表的长度。 +- `sin_table`: + sin 表指针。 +- `cos_table`: + cos 表指针。 +- `stream`: + 计算流/队列。 + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_NULL_POINTER`], [`INFINI_STATUS_INSUFFICIENT_WORKSPACE`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`], [`INFINI_STATUS_INTERNAL_ERROR`]. + +### 创建算子描述 + +```c +infiniStatus_t infiniopCreateRoPEDescriptor( + infiniopHandle_t handle, + infiniopRoPEDescriptor_t *desc_ptr, + infiniopTensorDescriptor_t y, + infiniopTensorDescriptor_t x, + infiniopTensorDescriptor_t pos_ids, + infiniopTensorDescriptor_t sin_table, + infiniopTensorDescriptor_t cos_table +); +``` + +
参数：
+ +- `handle` + : 硬件控柄。详见 [`InfiniopHandle_t`]。 +- `desc_ptr`: + `infiniopRoPEDescriptor_t` 指针，指向将被初始化的算子描述符地址。 +- `y` - { dT | (seq_len, num_head, head_dim) | (..., 1) }: + 三维张量。最后一维必须连续，且长度 `head_dim` 为2的倍数。 +- `x` - { dT | (seq_len, num_head, head_dim) | (..., 1) }: + 限制与 `y` 相同。 +- `pos_ids` - { dI | (seq_len) | (~) }: + 位置信息张量描述。张量必须为一维连续张量，长度为 `seq_len` 。用户需自行保证位置数据中所有数值小于 `max_seq_len`。 +- `sin_table` - { dT | (max_seq_len, head_dim/2) | (~) }: + sin 值表的张量描述，二维连续张量。 +- `cos_table` - { dT | (max_seq_len, head_dim/2) | (~) }: + cos 值表的张量描述，要求与 sin 表相同。 + +参数限制： + +- `dT`: (`Float16`, `Float32`, `Float64`) 之一。 +- `dI`: 任意整数类型。 + +
返回值：
+ +- [`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 infiniopGetRoPEWorkspaceSize( + infiniopRoPEDescriptor_t desc, + size_t *size +); +``` + +
参数：
+ +- `desc`: + 已使用 `infiniopCreateRoPEDescriptor()` 初始化的算子描述符。 +- `size`: + 额外空间大小的计算结果的写入地址。 + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_BAD_PARAM`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`]. + +### 销毁算子描述符 + +```c +infiniStatus_t infiniopDestroyRoPEDescriptor( + infiniopRoPEDescriptor_t desc +); +``` + +
参数：
+ +- `desc`: + 待销毁的算子描述符。 + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`]. + +## 已知问题 + +无 + + +[`InfiniopHandle_t`]: /infiniop/handle/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_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_NULL_POINTER`]:/common/status/README.md#INFINI_STATUS_NULL_POINTER +[`INFINI_STATUS_INSUFFICIENT_WORKSPACE`]:/common/status/README.md#INFINI_STATUS_INSUFFICIENT_WORKSPACE +[`INFINI_STATUS_INTERNAL_ERROR`]:/common/status/README.md#INFINI_STATUS_INTERNAL_ERROR diff --git a/InfiniCore-doc/infiniop/ops/sigmoid_backward/README.md b/InfiniCore-doc/infiniop/ops/sigmoid_backward/README.md new file mode 100644 index 0000000000000000000000000000000000000000..cef7d78e453c1e20e26de4afb44fccac054e6093 --- /dev/null +++ b/InfiniCore-doc/infiniop/ops/sigmoid_backward/README.md @@ -0,0 +1,134 @@ +# `Sigmoid Backward` + +`Sigmoid Backward`, 即**Sigmoid反向传播**算子，用于计算Sigmoid函数的梯度。其计算可被表述为： + +$$ grad\_input = grad\_output \times sigmoid(input) \times (1 - sigmoid(input)) $$ + +其中 `input` 为前向传播的输入，`grad_output` 为从后续层传回的梯度，`grad_input` 为计算得到的输入梯度。 + +## 接口 + +### 计算 + +```c +infiniStatus_t infiniopSigmoidBackward( + infiniopSigmoidBackwardDescriptor_t desc, + void *workspace, + size_t workspace_size, + void *grad_input, + const void *input, + const void *grad_output, + void *stream +); +``` + +
参数：
+ +- `desc`: + 已使用 `infiniopCreateSigmoidBackwardDescriptor()` 初始化的算子描述符； +- `workspace`: + 指向算子计算所需的额外工作空间； +- `workspace_size`: + `workspace` 的大小，单位：字节； +- `grad_input`: + 输出的输入梯度张量。张量限制见[创建算子描述](#创建算子描述)部分； +- `input`: + 前向传播的输入张量。张量限制见[创建算子描述](#创建算子描述)部分； +- `grad_output`: + 从后续层传回的梯度张量。张量限制见[创建算子描述](#创建算子描述)部分； +- `stream`: + 计算流/队列； + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_BAD_PARAM`], [`INFINI_STATUS_INSUFFICIENT_WORKSPACE`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`], [`INFINI_STATUS_INTERNAL_ERROR`]，[`INFINI_STATUS_BAD_TENSOR_DTYPE`]. + +### 创建算子描述 + +```c +infiniStatus_t infiniopCreateSigmoidBackwardDescriptor( + infiniopHandle_t handle, + infiniopSigmoidBackwardDescriptor_t *desc_ptr, + infiniopTensorDescriptor_t grad_input, + infiniopTensorDescriptor_t input, + infiniopTensorDescriptor_t grad_output +); +``` + +
参数：
+ +- `handle`: + `infiniopHandle_t` 类型的硬件控柄。详情请看：[`InfiniopHandle_t`]。 +- `desc_ptr`: + `infiniopSigmoidBackwardDescriptor_t` 指针，指向将被初始化的算子描述符地址； +- `grad_input` - { dT | (d1,...,dn) | (...) }: + 算子计算参数 `grad_input` 的张量描述，支持原位计算。 +- `input` - { dT | (d1,...,dn) | (...) }: + 算子计算参数 `input` 的张量描述。 +- `grad_output` - { dT | (d1,...,dn) | (...) }: + 算子计算参数 `grad_output` 的张量描述，支持原位计算。 + +参数限制： + +- `dT`: (`Float16`, `Float32`, `BFloat16`) 之一。 +- 所有张量 `input`、`grad_output` 与 `grad_input` 的形状需相同。 +- 支持原位计算，即计算时 `grad_input` 可以和 `grad_output` 指向同一地址。 +- 所有张量类型一致。 + +
返回值：
+ +- [`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 infiniopGetSigmoidBackwardWorkspaceSize( + infiniopSigmoidBackwardDescriptor_t desc, + size_t *size +); +``` + +
参数：
+ +- `desc`: + 已使用 `infiniopCreateSigmoidBackwardDescriptor()` 初始化的算子描述符； +- `size`: + 额外空间大小的计算结果的写入地址； + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_NULL_POINTER`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`]. + +### 销毁算子描述符 + +```c +infiniStatus_t infiniopDestroySigmoidBackwardDescriptor( + infiniopSigmoidBackwardDescriptor_t desc +); +``` + +
参数：
+ +- `desc`: + 输入。 待销毁的算子描述符； + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`]. + +## 已知问题 + +无 + + +[`InfiniopHandle_t`]: /infiniop/handle/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_NULL_POINTER`]: /common/status/README.md#INFINI_STATUS_NULL_POINTER +[`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 \ No newline at end of file diff --git a/InfiniCore-doc/infiniop/ops/sin/README.md b/InfiniCore-doc/infiniop/ops/sin/README.md new file mode 100644 index 0000000000000000000000000000000000000000..bdef3d21a09616819d544e74b28fb6937c0ce033 --- /dev/null +++ b/InfiniCore-doc/infiniop/ops/sin/README.md @@ -0,0 +1,128 @@ +# `Sin` + +`Sin`, 即**正弦**算子，为单目逐元素算子。其计算可被表述为： + +$$ output = \sin(input) $$ + +其中 `input` 为输入，`output` 为输出。 + +## 接口 + +### 计算 + +```c +infiniStatus_t infiniopSin( + infiniopSinDescriptor_t desc, + void *workspace, + size_t workspace_size, + void *output, + const void *input, + void *stream +); +``` + +
参数：
+ +- `desc`: + 已使用 `infiniopCreateSinDescriptor()` 初始化的算子描述符； +- `workspace`: + 指向算子计算所需的额外工作空间； +- `workspace_size`: + `workspace` 的大小，单位：字节； +- `output`: + 输出张量。张量限制见[创建算子描述](#创建算子描述)部分； +- `input`: + 输入张量。张量限制见[创建算子描述](#创建算子描述)部分； +- `stream`: + 计算流/队列； + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_BAD_PARAM`], [`INFINI_STATUS_INSUFFICIENT_WORKSPACE`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`], [`INFINI_STATUS_INTERNAL_ERROR`]，[`INFINI_STATUS_BAD_TENSOR_DTYPE`]. + +### 创建算子描述 + +```c +infiniStatus_t infiniopCreateSinDescriptor( + infiniopHandle_t handle, + infiniopSinDescriptor_t *desc_ptr, + infiniopTensorDescriptor_t output, + infiniopTensorDescriptor_t input +); +``` + +
参数：
+ +- `handle`: + `infiniopHandle_t` 类型的硬件控柄。详情请看：[`InfiniopHandle_t`]。 +- `desc_ptr`: + `infiniopSinDescriptor_t` 指针，指向将被初始化的算子描述符地址； +- `output` - { dT | (d1,...,dn) | (...) }: + 算子计算参数 `output` 的张量描述，支持原位计算。 +- `input` - { dT | (d1,...,dn) | (...) }: + 算子计算参数 `input` 的张量描述，支持原位计算。 + +参数限制： + +- `dT`: (`Float16`, `Float32`, `BFloat16`) 之一。 +- 输入 `input` 与输出 `output` 的形状需相同。 +- 支持原位计算，即计算时 `output` 可以和 `input` 指向同一地址。 +- 输入输出类型一致。 + +
返回值：
+ +- [`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 infiniopGetSinWorkspaceSize( + infiniopSinDescriptor_t desc, + size_t *size +); +``` + +
参数：
+ +- `desc`: + 已使用 `infiniopCreateSinDescriptor()` 初始化的算子描述符； +- `size`: + 额外空间大小的计算结果的写入地址； + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_NULL_POINTER`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`]. + +### 销毁算子描述符 + +```c +infiniStatus_t infiniopDestroySinDescriptor( + infiniopSinDescriptor_t desc +); +``` + +
参数：
+ +- `desc`: + 输入。 待销毁的算子描述符； + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`]. + +## 已知问题 + +无 + + +[`InfiniopHandle_t`]: /infiniop/handle/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_NULL_POINTER`]: /common/status/README.md#INFINI_STATUS_NULL_POINTER +[`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 \ No newline at end of file diff --git a/InfiniCore-doc/infiniop/ops/softmax/README.md b/InfiniCore-doc/infiniop/ops/softmax/README.md new file mode 100644 index 0000000000000000000000000000000000000000..b9d8d11c5567a9bf2df741a79e9c13ff7cd8b819 --- /dev/null +++ b/InfiniCore-doc/infiniop/ops/softmax/README.md @@ -0,0 +1,97 @@ + +# `Softmax` + +归一化指数函数，常用于讲输入数据转换为概率分布。对于长度为 $N$ 的一维张量 $x$ ，其公式为： + +$$ y_i = \frac{e^{x_i}}{\sum_{i=0}^{N - 1} e^{x_i}} $$ + +对于多维输入的情况，则在指定的维度 axis 上执行归一化计算。 + +## 接口 + +### 计算 + +```c +infiniStatus_t infiniopSoftmax( + infiniopSoftmaxDescriptor_t desc, + void *y, + const void *x, + void *stream +); +``` + +
参数：
+ +- `desc`：已使用 `infiniopCreateSoftmaxDescriptor()` 初始化的算子描述符。 +- `y`：输出指针。 +- `x`：输入指针，可以与 `y` 相同。 +- `stream`：计算流/队列。 + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_BAD_PARAM`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`] + +--- + +### 创建算子描述 + +```c +infiniStatus_t infiniopCreateSoftmaxDescriptor( + infiniopHandle_t handle, + infiniopSoftmaxDescriptor_t *desc_ptr, + infiniopTensorDescriptor_t y, + infiniopTensorDescriptor_t x, + int axis +); +``` + +
参数：
+ +- `handle`: 硬件控柄。详情请看 [`InfiniopHandle_t`] +- `desc_ptr`: `infiniopSoftmaxDescriptor_t` 指针，指向将被初始化的算子描述符地址。 +- `y` - { dT | (d1, $\ldots$ , dr) | ($\ldots$) } : 输出 `y` 的张量描述。 +- `x` - { dT | (d1, $\ldots$ , dr) | ($\ldots$) }: 算子计算参数 `x` 的张量描述，张量形状和 `y` 保持一致。 +- `axis`: 执行规约的维度。可选择范围是 $[-\text{r}, \text{r} - 1]$，其中 $\text{r}$ 是 `x` 的秩。当 `axis` 为负数时，表示倒数第 `axis` 个维度。 + +参数限制： + +- **`dT`**: (`Float16`, `Float32`, `Float64`) 之一。 + +
返回值：
+ +- [`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 infiniopDestroySoftmaxDescriptor( + infiniopSoftmaxDescriptor_t desc +); +``` + +
参数：
+ +- `desc` + : 待销毁的算子描述符。 + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`]. + +## 已知问题 + +### 平台限制 + +- 寒武纪中 tensor.to(device) 的 tensor 不支持 uint64 或者是 int64 数据类型。 + + +[`InfiniopHandle_t`]: /infiniop/handle/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_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 diff --git a/InfiniCore-doc/infiniop/ops/sub/README.md b/InfiniCore-doc/infiniop/ops/sub/README.md new file mode 100644 index 0000000000000000000000000000000000000000..aaa02beb0858625e4fae0cf110e239abfb743908 --- /dev/null +++ b/InfiniCore-doc/infiniop/ops/sub/README.md @@ -0,0 +1,135 @@ + +# `Sub` + +`Sub`, 即**减法**算子，为双目逐元素算子。其计算可被表述为： + +$$ c = a - b $$ + +其中 a 和 b 为输入，c 为输出。 + +## 接口 + +### 计算 + +```c +infiniStatus_t infiniopSub( + infiniopSubDescriptor_t desc, + void *workspace, + size_t workspace_size, + void *c, + const void *a, + const void *b, + void *stream +); +``` + +
参数：
+ +- `desc`: + 已使用 `infiniopCreateSubDescriptor()` 初始化的算子描述符； +- `workspace`: + 指向算子计算所需的额外工作空间； +- `workspace_size`: + `workspace` 的大小，单位：字节； +- `c`: + 输出张量。张量限制见[创建算子描述](#创建算子描述)部分； +- `a`: + 输入张量。张量限制见[创建算子描述](#创建算子描述)部分； +- `b`: + 输入张量。张量限制见[创建算子描述](#创建算子描述)部分； +- `stream`: + 计算流/队列； + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_BAD_PARAM`], [`INFINI_STATUS_INSUFFICIENT_WORKSPACE`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`], [`INFINI_STATUS_INTERNAL_ERROR`]，[`INFINI_STATUS_BAD_TENSOR_DTYPE`]. + +### 创建算子描述 + +```c +infiniStatus_t infiniopCreateSubDescriptor( + infiniopHandle_t handle, + infiniopSubDescriptor_t *desc_ptr, + infiniopTensorDescriptor_t c_desc, + infiniopTensorDescriptor_t a_desc, + infiniopTensorDescriptor_t b_desc +); +``` + +
参数：
+ +- `handle`: + `infiniopHandle_t` 类型的硬件控柄。详情请看：[`InfiniopHandle_t`]。 +- `desc_ptr`: + `infiniopSubDescriptor_t` 指针，指向将被初始化的算子描述符地址； +- `c_desc` - { dT | (d1,...,dn) | (...) }: + 算子计算参数 `c` 的张量描述，支持原位计算。 +- `a_desc` - { dT | (d1,...,dn) | (...) }: + 算子计算参数 `a` 的张量描述，支持原位计算，支持多向广播。 +- `b_desc` - { dT | (d1,...,dn) | (...) }: + 算子计算参数 `b` 的张量描述，支持原位计算，支持多向广播。 + +参数限制： + +- `dT`: (`Float16`, `Float32`, `Float64`, `BFloat16`) 之一。 +- 输入 `a` 与 `b` 的形状需与 `c` 相同。`a` 与 `b` 涉及多向广播时需调整步长以匹配多向广播的映射关系。 +- 支持原位计算，即计算时 `c` 可以和 `a` 或 `b` 指向同一地址。 +- 计算输出参数 `c` 不能进行广播（`c` 的步长不能涉及广播设置，即步长不能有 0） + +
返回值：
+ +- [`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 infiniopGetSubWorkspaceSize( + infiniopSubDescriptor_t desc, + size_t *size +); +``` + +
参数：
+ +- `desc`: + 已使用 `infiniopCreateSubDescriptor()` 初始化的算子描述符； +- `size`: + 额外空间大小的计算结果的写入地址； + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_NULL_POINTER`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`]. + +### 销毁算子描述符 + +```c +infiniStatus_t infiniopDestroySubDescriptor( + infiniopSubDescriptor_t desc +); +``` + +
参数：
+ +- `desc`: + 输入。 待销毁的算子描述符； + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`]. + +## 已知问题 + +无 + + +[`InfiniopHandle_t`]: /infiniop/handle/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_NULL_POINTER`]: /common/status/README.md#INFINI_STATUS_NULL_POINTER +[`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 diff --git a/InfiniCore-doc/infiniop/ops/swiglu/README.md b/InfiniCore-doc/infiniop/ops/swiglu/README.md new file mode 100644 index 0000000000000000000000000000000000000000..4c278728911b37f6beab505d64ce621cf17bda06 --- /dev/null +++ b/InfiniCore-doc/infiniop/ops/swiglu/README.md @@ -0,0 +1,118 @@ + +# `SwiGLU` + +`SwiGLU (Switched Gated Linear Unit)` , 即**门控线性单元激活函数**算子，计算公式为： + +$$ +c_{i} = a_{i} \circ SiLU(b_{i}) +$$ + +$$ +SiLU(b_{i}) = \frac {b_{i}}{1 + e^{-b_{i}}} +$$ + +其中： + +- $c_{i}$: 输出张量第 `i` 个元素。 +- $a_{i}$: 输入张量第 `i` 个元素。 +- $b_{i}$: 门控输入张量第 `i` 个元素。 + +## 接口 + +### 计算 + +```c +infiniStatus_t infiniopSwiGLU( + infiniopSwiGLUDescriptor_t desc, + void *c, + const void *a, + const void *b, + void *stream +); +``` + +
参数：
+ +- `desc`: + 已使用 `infiniopCreateSwiGLUDescriptor()` 初始化的算子描述符。 +- `c`: + 输出张量，张量限制见[创建算子描述](#创建算子描述)部分。 +- `a`: + 输入张量，张量限制见[创建算子描述](#创建算子描述)部分。 +- `b`: + 门控输入张量，张量限制见[创建算子描述](#创建算子描述)部分。 +- `stream`: + 计算流/队列。 + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`STATUS_MEMORY_NOT_ALLOCATED`], [`STATUS_BAD_TENSOR_SHAPE`], [`STATUS_BAD_TENSOR_STRIDES`], [`STATUS_BAD_TENSOR_DTYPE`]. + +### 创建算子描述 + +```c +infiniStatus_t infiniopCreateSwiGLUDescriptor( + infiniopHandle_t handle, + infiniopSwiGLUDescriptor_t *desc_ptr, + infiniopTensorDescriptor_t c, + infiniopTensorDescriptor_t a, + infiniopTensorDescriptor_t b +); +``` + +
参数：
+ +- `handle` + : `infiniopHandle_t` 类型的硬件控柄。详情请看：[`InfiniopHandle_t`]。 +- `desc_ptr`: + `infiniopSwiGLUDescriptor_t` 指针，指向将被初始化的算子描述符地址。 +- `c` - { dT | (...) | (...) }: + 算子计算参数 `c` 的张量描述, 支持原位计算。 +- `a` - { dT | (...) | (...) }: + 算子计算参数 `a` 的张量描述，支持原位计算。 +- `b` - { dT | (...) | (...) }: + 算子计算参数 `b` 的张量描述，支持原位计算。 + +参数限制： + +- `dT`: (`Float16`, `Float32`, `Float64`, `Bfloat16`) 之一 +- `c`, `a`, `b` 均支持不连续步长 + +
返回值：
+ +- [`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 infiniopDestroySwiGLUDescriptor( + infiniopSwiGLUDescriptor_t desc +); +``` + +
参数：
+ +- `desc`: + 输入。待销毁的算子描述符。 + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`]. + +## 已知问题 + +无 + + +[`InfiniopHandle_t`]: /infiniop/handle/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_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 +[`STATUS_MEMORY_NOT_ALLOCATED`]:/common/status/README.md#STATUS_MEMORY_NOT_ALLOCATED +[`STATUS_BAD_TENSOR_SHAPE`]:/common/status/README.md#STATUS_BAD_TENSOR_SHAPE +[`STATUS_BAD_TENSOR_STRIDES`]:/common/status/README.md#STATUS_BAD_TENSOR_STRIDES +[`STATUS_BAD_TENSOR_DTYPE`]:/common/status/README.md#STATUS_BAD_TENSOR_DTYPE diff --git a/InfiniCore-doc/infiniop/ops/tanh/README.md b/InfiniCore-doc/infiniop/ops/tanh/README.md new file mode 100644 index 0000000000000000000000000000000000000000..221a5a4f65fd386abba79ff9f207494cf2959905 --- /dev/null +++ b/InfiniCore-doc/infiniop/ops/tanh/README.md @@ -0,0 +1,128 @@ +# `Tanh` + +`Tanh`, 即**双曲正切**算子，为单目逐元素算子。其计算可被表述为： + +$$ output = \tanh(input) = \frac{e^{input} - e^{-input}}{e^{input} + e^{-input}} $$ + +其中 `input` 为输入，`output` 为输出。 + +## 接口 + +### 计算 + +```c +infiniStatus_t infiniopTanh( + infiniopTanhDescriptor_t desc, + void *workspace, + size_t workspace_size, + void *output, + const void *input, + void *stream +); +``` + +
参数：
+ +- `desc`: + 已使用 `infiniopCreateTanhDescriptor()` 初始化的算子描述符； +- `workspace`: + 指向算子计算所需的额外工作空间； +- `workspace_size`: + `workspace` 的大小，单位：字节； +- `output`: + 输出张量。张量限制见[创建算子描述](#创建算子描述)部分； +- `input`: + 输入张量。张量限制见[创建算子描述](#创建算子描述)部分； +- `stream`: + 计算流/队列； + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_BAD_PARAM`], [`INFINI_STATUS_INSUFFICIENT_WORKSPACE`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`], [`INFINI_STATUS_INTERNAL_ERROR`]，[`INFINI_STATUS_BAD_TENSOR_DTYPE`]. + +### 创建算子描述 + +```c +infiniStatus_t infiniopCreateTanhDescriptor( + infiniopHandle_t handle, + infiniopTanhDescriptor_t *desc_ptr, + infiniopTensorDescriptor_t output, + infiniopTensorDescriptor_t input +); +``` + +
参数：
+ +- `handle`: + `infiniopHandle_t` 类型的硬件控柄。详情请看：[`InfiniopHandle_t`]。 +- `desc_ptr`: + `infiniopTanhDescriptor_t` 指针，指向将被初始化的算子描述符地址； +- `output` - { dT | (d1,...,dn) | (...) }: + 算子计算参数 `output` 的张量描述，支持原位计算。 +- `input` - { dT | (d1,...,dn) | (...) }: + 算子计算参数 `input` 的张量描述，支持原位计算。 + +参数限制： + +- `dT`: (`Float16`, `Float32`, `BFloat16`) 之一。 +- 输入 `input` 与输出 `output` 的形状需相同。 +- 支持原位计算，即计算时 `output` 可以和 `input` 指向同一地址。 +- 输入输出类型一致。 + +
返回值：
+ +- [`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 infiniopGetTanhWorkspaceSize( + infiniopTanhDescriptor_t desc, + size_t *size +); +``` + +
参数：
+ +- `desc`: + 已使用 `infiniopCreateTanhDescriptor()` 初始化的算子描述符； +- `size`: + 额外空间大小的计算结果的写入地址； + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_NULL_POINTER`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`]. + +### 销毁算子描述符 + +```c +infiniStatus_t infiniopDestroyTanhDescriptor( + infiniopTanhDescriptor_t desc +); +``` + +
参数：
+ +- `desc`: + 输入。 待销毁的算子描述符； + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`]. + +## 已知问题 + +无 + + +[`InfiniopHandle_t`]: /infiniop/handle/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_NULL_POINTER`]: /common/status/README.md#INFINI_STATUS_NULL_POINTER +[`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 \ No newline at end of file diff --git a/InfiniCore-doc/infiniop/ops/where/README.md b/InfiniCore-doc/infiniop/ops/where/README.md new file mode 100644 index 0000000000000000000000000000000000000000..c77423f2283d6fde4641c6e29154eb833142d5ee --- /dev/null +++ b/InfiniCore-doc/infiniop/ops/where/README.md @@ -0,0 +1,144 @@ +# `Where` + +`Where`, 即**条件选择**算子，为三目逐元素算子。其计算可被表述为： + +$$ c[i] = \begin{cases} +a[i] & \text{if } condition[i] \text{ is true} \\ +b[i] & \text{if } condition[i] \text{ is false} +\end{cases} $$ + +其中 `condition` 为条件张量（布尔类型），`a` 和 `b` 为输入张量，`c` 为输出张量。 + +## 接口 + +### 计算 + +```c +infiniStatus_t infiniopWhere( + infiniopWhereDescriptor_t desc, + void *workspace, + size_t workspace_size, + const void *condition, + const void *a, + const void *b, + void *c, + void *stream +); +``` + +
参数：
+ +- `desc`: + 已使用 `infiniopCreateWhereDescriptor()` 初始化的算子描述符； +- `workspace`: + 指向算子计算所需的额外工作空间； +- `workspace_size`: + `workspace` 的大小，单位：字节； +- `condition`: + 条件张量（布尔类型）。张量限制见[创建算子描述](#创建算子描述)部分； +- `a`: + 输入张量a。张量限制见[创建算子描述](#创建算子描述)部分； +- `b`: + 输入张量b。张量限制见[创建算子描述](#创建算子描述)部分； +- `c`: + 输出张量。张量限制见[创建算子描述](#创建算子描述)部分； +- `stream`: + 计算流/队列； + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_BAD_PARAM`], [`INFINI_STATUS_INSUFFICIENT_WORKSPACE`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`], [`INFINI_STATUS_INTERNAL_ERROR`]，[`INFINI_STATUS_BAD_TENSOR_DTYPE`]. + +### 创建算子描述 + +```c +infiniStatus_t infiniopCreateWhereDescriptor( + infiniopHandle_t handle, + infiniopWhereDescriptor_t *desc_ptr, + infiniopTensorDescriptor_t condition, + infiniopTensorDescriptor_t a, + infiniopTensorDescriptor_t b, + infiniopTensorDescriptor_t c +); +``` + +
参数：
+ +- `handle`: + `infiniopHandle_t` 类型的硬件控柄。详情请看：[`InfiniopHandle_t`]。 +- `desc_ptr`: + `infiniopWhereDescriptor_t` 指针，指向将被初始化的算子描述符地址； +- `condition` - { Bool | (d1,...,dn) | (...) }: + 算子计算参数 `condition` 的张量描述。 +- `a` - { dT | (d1,...,dn) | (...) }: + 算子计算参数 `a` 的张量描述，支持原位计算。 +- `b` - { dT | (d1,...,dn) | (...) }: + 算子计算参数 `b` 的张量描述，支持原位计算。 +- `c` - { dT | (d1,...,dn) | (...) }: + 算子计算参数 `c` 的张量描述，支持原位计算。 + +参数限制： + +- `dT`: (`Float16`, `Float32`, `BFloat16`) 之一。 +- `condition` 的数据类型必须为 `Bool`。 +- 所有张量 `condition`、`a`、`b` 和 `c` 的形状需相同。 +- 支持原位计算，即计算时 `c` 可以和 `a` 或 `b` 指向同一地址。 +- 输入输出类型一致（`a`、`b`、`c` 类型相同）。 + +
返回值：
+ +- [`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 infiniopGetWhereWorkspaceSize( + infiniopWhereDescriptor_t desc, + size_t *size +); +``` + +
参数：
+ +- `desc`: + 已使用 `infiniopCreateWhereDescriptor()` 初始化的算子描述符； +- `size`: + 额外空间大小的计算结果的写入地址； + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_NULL_POINTER`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`]. + +### 销毁算子描述符 + +```c +infiniStatus_t infiniopDestroyWhereDescriptor( + infiniopWhereDescriptor_t desc +); +``` + +
参数：
+ +- `desc`: + 输入。 待销毁的算子描述符； + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_DEVICE_TYPE_NOT_SUPPORTED`]. + +## 已知问题 + +无 + + +[`InfiniopHandle_t`]: /infiniop/handle/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_NULL_POINTER`]: /common/status/README.md#INFINI_STATUS_NULL_POINTER +[`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 \ No newline at end of file diff --git a/InfiniCore-doc/infiniop/tensor/README.md b/InfiniCore-doc/infiniop/tensor/README.md new file mode 100644 index 0000000000000000000000000000000000000000..2ce16b1b85729ca820c1c23137649dfbbe09a91b --- /dev/null +++ b/InfiniCore-doc/infiniop/tensor/README.md @@ -0,0 +1,75 @@ +# 张量描述（`InfiniopTensorDescriptor_t`） + +张量（Tensor）是一种表示多维数据的数据结构，可用来表示算子的输入与输出。一个张量由描述它数据形态的元信息和实际数据两部分组成。在 *InfiniOP* 中，张量的元信息和数据是解耦的。算子描述符（`InfiniopTensorDescriptor_t`）被用来保存某一张量的元信息。 + +算子描述符会记录张量的三个重要信息：数据类型（data type）、形状（shape）、步长（strides）。一个张量中的所有数据的类型必须相同，支持的数据类型详见 [`InfiniDtype_t`]。形状和步长是两个长度相同的数组。形状包含每个维度的元素个数，步长包含每个维度从一个元素到下一个元素的元素数间隔。 + +## 张量数据的排布与索引 + +`InfiniOP` 的张量描述比起一些传统的张量表示方式（如 ONNX）额外引入了步长信息，可以表示更复杂的张量数据排布方式。对于一些不涉及数学计算的操作，如转置（transpose）、切片（slice）等，可以通过只变换元信息来表示，无需移动数据。这为用户提供了更多的性能优化空间。当用户确实需要重新排布数据时，可以使用 [`Rearrange`] 算子。 + +引入步长信息后，张量数据的索引方式如下：假设一个张量的数据起始地址为 `addr`，数据类型为 `T`, 每个元素的数据大小为 `size(T)` 个字节，形状为 `(d1, d2)`，步长为 `(s1, s2)`，那么该张量第3行第2列的数据地址的计算方式为： + +```c +addr + ((3 -1) * s1 + (2 - 1) * s2) * size(T) +``` + +当形状和步长的长度为0时，代表标量。当某一个维的步长为0且长度不为1时，则该维度为广播维度，同样的数据会在此维度上重复出现。当一个维度的步长为负数时，此维度的元素索引方向为反向。 + +## 算子对张量的限制 + +不同的算子对输入输出的张量的数据类型、形状和步长往往有各种各样的限制。在文档中，会使用 `{数据类型; 形状; 步长}` 的写法来对编程接口所涉及的张量进行描述和限定。 + +示例： + +- `{ float32 | (d1, d2) | (..., 1) }`：类型为 `float32`，维度为两维（用`d1`、`d2`表示），最后一维步长为 `1`（即该维度数据连续排布），其他维度步长不做限制。 + +- `{ dT | ((b,) h, w, c) | (...) }`：类型可能支持多种，用 `dT` 表示（后续可增加限制说明），维度可能为三维或四维（`b` 维度可有可无），步长不做限制。 + +- `{ dT | ((...,) m, n) | (~) }`：类型可能支持多种，维度为二维或以上，步长需满足所有维度全部连续。 + +## 接口 + +### 创建张量描述 + +```c +infiniStatus_t infiniopCreateTensorDescriptor( + infiniopTensorDescriptor_t *desc_ptr, + size_t ndim, + const size_t *shape, + const ptrdiff_t *strides, + infiniDtype_t dtype +); +``` + +- `desc_ptr`: 存储将被创建的张量描述的地址。 +- `ndim`: 张量的维度数量，维度数量为 $0$ 时则为标量。 +- `shape`: 形状数组地址，标量可传入 `nullptr`，其他情况用户需要传入长度足够的有效地址。 +- `strides`: 步长数组地址，若传入 `nullptr` 则默认数据完全连续，其他情况用户需要转入长度足够的有效地址，步长支持负数。 +- `dtype`: 数据类型，详见 [`InfiniDtype_t`]。 + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`], [`INFINI_STATUS_NULL_POINTER`] + +### 销毁张量描述符 + +```c +infiniStatus_t infiniopDestroyTensorDescriptor( + infiniopTensorDescriptor_t desc +); +``` + +
参数：
+ +- `desc`: 待销毁的张量描述。 + +
返回值：
+ +- [`INFINI_STATUS_SUCCESS`] + + +[`InfiniDtype_t`]: /common/dtype/README.md +[`INFINI_STATUS_SUCCESS`]: /common/status/README.md#INFINI_STATUS_SUCCESS +[`INFINI_STATUS_NULL_POINTER`]: /common/status/README.md#INFINI_STATUS_NULL_POINTER +[`Rearrange`]: /infiniop/ops/rearrange/README.md diff --git a/InfiniCore-doc/infinirt/README.md b/InfiniCore-doc/infinirt/README.md new file mode 100644 index 0000000000000000000000000000000000000000..e80d2d35d8209d46f923d2482d17ea70bf47eb8c --- /dev/null +++ b/InfiniCore-doc/infinirt/README.md @@ -0,0 +1,229 @@ + +# `InfiniRT` 统一运行时库 + +## 简介 + +*InfiniRT* 是一个跨平台统一运行时库，对不同芯片平台的运行时和驱动功能进行了统一封装。 + +## 编程接口 + +### 1. 设备管理 + +#### 初始化设备环境 + +``` c++ +infiniStatus_t infinirtInit(); +``` + +- 初始化所有可用设备类型的运行时环境（如启用的 Ascend）。 +- 仅在使用前调用一次。 +#### 获得设备所有设备数量 + +``` c++ +infiniStatus_t infinirtGetAllDeviceCount(int *count_array); +``` + +- `count_array`: 数组长度至少为 [`infiniDevice_t`] 中设备种类数量，每种设备数量会写入数组的相应位置。 + +#### 获取当前设备信息 + +``` c++ +infiniStatus_t infinirtGetDevice(infiniDevice_t *device_ptr, int *device_id_ptr); +``` + +- device_ptr: 返回当前设备类型（可为 nullptr）。 + +- device_id_ptr: 返回当前设备 ID（可为 nullptr）。 +#### 获得特定设备数量 + +``` c++ +infiniStatus_t infinirtGetDeviceCount(infiniDevice_t device, int *count); +``` + +- `device`: 设备种类。 +- `count`: 存储设备数量查询结果的指针。 + +#### 设置当前使用的设备 + +``` c++ +infiniStatus_t infinirtSetDevice(infiniDevice_t device, int device_id); +``` + +- device: 要设置的设备类型。 +- device_id: 要设置的设备 ID。 + +#### 同步当前设备 + +``` c++ +infiniStatus_t infinirtDeviceSynchronize(); +``` + +- 阻塞直到当前设备完成所有计算。 + +### 2. 流管理 + +#### 创建设备流（Stream） + +``` c++ +infiniStatus_t infinirtStreamCreate(infinirtStream_t *stream_ptr); +``` + +- stream_ptr: 返回创建的 stream 对象。 + +#### 销毁设备流 + +``` c++ +infiniStatus_t infinirtStreamDestroy(infinirtStream_t stream); +``` + +- stream: 需要销毁的 stream 对象。 + +#### 等待流中所有任务完成 + +``` c++ +infiniStatus_t infinirtStreamSynchronize(infinirtStream_t stream); +``` + +- stream: 需要同步的 stream。 + +#### 让一个流等待一个事件 + +``` c++ +infiniStatus_t infinirtStreamWaitEvent(infinirtStream_t stream, infinirtEvent_t event); +``` + +- stream: 需要等待的流。 +- event: 被等待的事件。 + +### 3. 事件管理 +#### 创建事件 + +``` c++ +infiniStatus_t infinirtEventCreate(infinirtEvent_t *event_ptr); +``` + +- event_ptr: 返回创建的事件。 + +#### 记录事件 + +``` c++ +infiniStatus_t infinirtEventRecord(infinirtEvent_t event, infinirtStream_t stream); +``` + +- event: 要记录的事件。 +- stream: 事件记录在哪个流上。 + +#### 查询事件状态 + +``` c++ +infiniStatus_t infinirtEventQuery(infinirtEvent_t event, infinirtEventStatus_t *status_ptr); +``` + +- event: 需要查询的事件。 +- status_ptr: 返回事件状态（已完成 / 未完成等）。 + +#### 等待事件完成 + +``` c++ +infiniStatus_t infinirtEventSynchronize(infinirtEvent_t event); +``` + +- event: 要等待的事件。 + +#### 销毁事件 + +``` c++ +infiniStatus_t infinirtEventDestroy(infinirtEvent_t event); +``` + +- event: 需要销毁的事件。 + +### 4. 内存管理 + +#### 分配设备内存 +``` c++ +infiniStatus_t infinirtMalloc(void **p_ptr, size_t size); +``` + +- p_ptr: 返回分配的内存指针。 +- size: 要分配的内存大小（单位：字节）。 + +#### 分配页锁定主机内存 + +``` c++ +infiniStatus_t infinirtMallocHost(void **p_ptr, size_t size); +``` + +- p_ptr: 返回分配的主机内存指针。 + +- size: 分配的内存大小（单位：字节）。 + +#### 释放设备内存 + +``` c++ +infiniStatus_t infinirtFree(void *ptr); +``` + +- ptr: 需要释放的设备内存指针。 + +#### 释放页锁定主机内存 + +``` c++ +infiniStatus_t infinirtFreeHost(void *ptr); +``` + + ptr: 需要释放的主机内存指针。 + +#### 同步内存拷贝 + +``` c++ +infiniStatus_t infinirtMemcpy(void *dst, const void *src, size_t size, infinirtMemcpyKind_t kind); +``` + +- dst: 目标地址。 +- src: 源地址。 +- size: 拷贝的字节数。 +- kind: 枚举类型infinirtMemcpyKind_t + 其定义如下： +``` c++ +typedef enum { + INFINIRT_MEMCPY_H2H = 0, //Host to Host + INFINIRT_MEMCPY_H2D = 1, //Host to Device + INFINIRT_MEMCPY_D2H = 2, //Device to Host + INFINIRT_MEMCPY_D2D = 3, //Device to Device +} infinirtMemcpyKind_t; + +``` + +#### 异步内存拷贝 + +``` c++ +infiniStatus_t infinirtMemcpyAsync(void *dst, const void *src, size_t size, infinirtMemcpyKind_t kind, infinirtStream_t stream); +``` + +- dst: 目标地址。 +- src: 源地址。 +- size: 拷贝的字节数。 +- kind: 拷贝类型(见[infinirtMemcpy](#同步内存拷贝))。 +- stream: 所用的异步流。 + +#### 异步分配设备内存 (Stream-ordered memory) + +``` c++ +infiniStatus_t infinirtMallocAsync(void **p_ptr, size_t size, infinirtStream_t stream); +``` + +- p_ptr: 返回分配的内存指针。 + +- size: 分配大小（单位：字节）。 + +- stream: 异步操作所用的流。 + +#### 异步释放设备内存 (Stream-ordered memory) + +``` c++ +infiniStatus_t infinirtFreeAsync(void *ptr, infinirtStream_t stream); +``` + +- ptr: 要释放的设备内存地址。 +- stream: 异步释放所用的流。