Merge pull request #317 from InfiniTensor/issue/316

issue/316 添加开发者手册

Merge pull request #317 from InfiniTensor/issue/316
issue/316 添加开发者手册
55f60c1c · PanZezhong1725 · GitHub · 65bed07e · 0eac5adc · 55f60c1c
Unverified Commit 55f60c1c authored Jul 12, 2025 by PanZezhong1725 Committed by GitHub Jul 12, 2025
Hide whitespace changes
Inline Side-by-side

Showing with 210 additions and 60 deletions

DEV.md DEV.md +204 -0

README.md README.md +4 -58

test/infiniop-test/README.md test/infiniop-test/README.md +2 -2

No files found.
--- a/DEV.md
+++ b/DEV.md
+# InfiniCore 开发者手册
+
+Dear 开发者，感谢你参与 InfiniCore 开源项目的开发！本文档将帮助你了解如何向 InfiniCore 项目贡献代码。
+
+## 项目介绍
+
+### 项目模块体系
+
+- infini-utils：全模块通用工具代码。
+- infinirt：运行时库，依赖 infini-utils。
+- infiniop：算子库，依赖 infinirt。除了 C++ 算子实现之外，也包括使用九齿（triton）的算子实现，这部分算子需要在编译之前使用脚本生成源文件。安装后可以运行位于 `test/infiniop` 中的单测脚本进行测试。
+- infiniccl：通信库，依赖 infinirt。
+- utils-test：工具库测试代码，依赖 infini-utils。
+- infiniop-test：算子库测试框架代码。与单测不同，读取gguf测例文件进行测试（详见[`测例文档`](test/infiniop-test/README.md)）。使用前需要安装好 infiniop。
+- infiniccl-test：通信库测试代码，使用前需要安装好 infiniccl。
+
+### 文件目录结构
+
+```bash
+├── xmake.lua  # 总体 xmake 编译配置，包含所有平台的编译选项和宏定义
+├── xmake/*.lua  # 各平台 xmake 编译配置， 包含各平台特有的编译方式
+│    
+├── include/  # 对外暴露的头文件目录，安装时会被复制到安装目录
+│   ├── infiniop/*.h  # InfiniOP算子库子头文件
+│   ├── *.h  # 模块核心头文件
+│ 
+├── src/  # 各模块源代码目录，包含源代码文件以及不对外暴露的头文件
+│   ├── infiniop/ # InfiniOP算子库源代码目录
+│   │   ├── devices/  # 每个设备平台各自的通用代码目录
+│   │   ├── ops/ # 算子实现代码目录
+│   │   │   ├── [op]/
+│   │   │   │   ├── [device]/ # 各硬件平台算子实现代码目录
+│   │   │   │   ├── operator.cc # 算子C语言接口实现
+│   │   ├── reduce/ # 规约类算子通用代码目录
+│   │   ├── elementwise/  # 逐元素类算子通用代码目录
+│   │   ├── *.h  # 核心结构体定义
+│   │
+│   ├── infiniop-test/  # InfiniOP算子库测试框架
+│   ├── infinirt/ # InfiniRT运行时库源代码目录
+│   ├── infiniccl/ # InfiniCCL集合通信库源代码目录
+│  
+├── test/ # 测试源代码目录
+│   ├── infiniop/ # InfiniOP算子库单元测试目录
+│   │       ├── *.py     # 单测脚本（依赖各平台PyTorch）
+│   ├── infiniop-test/
+│   │       ├── test_generate/ # 算子库测试框架测例生成脚本
+│  
+├── scripts/ # 脚本目录
+│   ├── install.py # 安装编译脚本
+│   ├── python_test.py # 运行所有单测脚本
+```
+
+## 开发引导
+
+### 代码提交流程
+
+1. 在github仓库issue页面根据任务类型（开发或bug）创建 issue，所有commit必须有对应的 issue 编号。
+2. 外部人员需要通过 fork 代码仓库提交 PR。
+3. 根据 issue 编号建立分支，分支名字格式为 `issue/#` （# 为issue 编号）。如果出现重复，可在后面添加“-#”序号，或用“/”后增加说明。
+4. 所有 commit 信息必须以 `issue/#` 开头，
+5. 分支推到远程后，建 Pull Request，标题需要以 `issue/#` 开头。在原issue页面上将该PR关联。
+6. PR必须添加至少两位审核员（模块负责人和项目管理员等），PR中需附上最后一次修改后测试通过的截图。
+7. PR通过审核，通过自动测试，无代码冲突后方可合并。合并后，关闭原 issue。
+
+### 如何开发一个新算子
+
+1. 根据算子定义设计算子接口，在 [`InfiniCore文档`](https://github.com/InfiniTensor/InfiniCore-Documentation) 中添加算子文档。提交文档 PR 。
+2. 在 `include/infiniop/` 中添加算子头文件，并 include 到 `include/infiniop.h` 中。
+3. 在 `src/infiniop/ops/` 中添加算子实现目录，并在目录中创建 `operator.cc` 文件实现头文件中的接口。
+4. 在 `src/infiniop/ops/[op]/[device]/` 中添加平台算子实现。注意复用平台公共代码（比如逐元素计算和规约计算），开发过程中把未来可复用的代码写在相应公用代码目录里。比如 cuda kernel 可以多个平台公用，可以考虑在头文件中实现，并在多个源文件中使用。
+5. 算子实现可以成功编译安装后，在 `test/infiniop/` 中添加单测脚本，与 PyTorch 实现进行正确性和性能比较。测例应覆盖算子常用类型和形状。测试成功之后可以将测例添加至 `scripts/python_test.py` 一键测试脚本中（这样 Github 自动测试也会包含该算子）。
+6. 在 `test/infiniop-test/` 算子测试框架中添加该算子的测例脚本。脚本应该包含构建该算子 gguf 测例的类，并在 main 函数中添加几个随机测例。验证随机 gguf 测例可以通过测试框架的测试程序。
+7. 按照流程提交代码 PR 。
+
+### C++ 代码命名书写规范
+
+1. 类型
+
+    内部数据结构类型 `UpperCamelCase`
+
+    ```c++
+    // 尽量使用 Infinixx 开头
+    struct InfiniopMatmulCudaDescriptor;
+    
+    template <typename KeyType, typename ValueType>
+    class HashMap; 
+    
+    using ValueMap = std::unordered_map<int, std::string>;
+    ```
+
+    对外暴露的指针类型和枚举类型 `infinixx[XxxXxx]_t`
+
+    常量使用 `INFINI_UPPER_SNAKE_CASE`
+
+    ```c++
+    typedef struct InfiniopMatmulCudaDescriptor *infiniopMatmulCudaDescriptor_t;
+    
+    typedef enum {
+        // INFINI...
+        INFINI_DTYPE_INVALID = 0,
+    } infiniDtype_t;
+    ```
+
+2. 普通变量、形参、类数据成员，使用 `snake_case`
+
+    成员名前下划线特指private成员，其他情况应避免使用前下划线
+
+    ```c++
+    int max_count;
+    
+    class Example {
+    public:
+        std::string getUserName(std::string user_id);
+    private:
+        // private数据成员名字前加下划线
+        int _max_count;
+        std::string _user_name;
+    };
+    
+    struct UrlTableProperties {  
+        string name;
+        int num_entries;  
+        static Pool<UrlTableProperties>* pool;
+    };
+    ```
+
+    当形参与函数内部变量或成员变量重名，可选择其中一个名字后加下划线。当函数内部临时变量和成员重名时，临时变量名字后加下划线。后下划线表示“临时”
+
+    ```c++
+    void do(int count_){
+        int count = count_;
+    }
+    ```
+
+3. 函数，使用 lowerCamelCase
+
+    ```c++
+    int getMaxValue() const;
+    ```
+
+4. const/volatile修饰符写在类型前面
+
+    ```c++
+    const void *ptr;
+    const int num;
+    ```
+
+### 代码格式化
+
+本项目分别使用 `clang-format-16` 和 `black` 对 C/C++ 以及 Python 代码进行格式化。可以使用 [`scripts/format.py`](/scripts/format.py) 脚本实现代码格式化检查和操作。
+
+使用
+
+```shell
+python scripts/format.py -h
+```
+
+查看脚本帮助信息：
+
+```plaintext
+usage: format.py [-h] [--ref REF] [--path [PATH ...]] [--check] [--c C] [--py PY]
+
+options:
+  -h, --help         show this help message and exit
+  --ref REF          Git reference (commit hash) to compare against.
+  --path [PATH ...]  Files to format or check.
+  --check            Check files without modifying them.
+  --c C              C formatter (default: clang-format-16)
+  --py PY            Python formatter (default: black)
+```
+
+参数中：
+
+- `ref` 和 `path` 控制格式化的文件范围
+  - 若 `ref` 和 `path` 都为空，格式化当前暂存（git added）的文件；
+  - 否则
+    - 若 `ref` 非空，将比较指定 commit 和当前代码的差异，只格式化修改过的文件；
+    - 若 `path` 非空，可传入多个路径（`--path p0 p1 p2`），只格式化指定路径及其子目录中的文件；
+- 若设置 `--check`，将检查代码是否需要修改格式，不修改文件内容；
+- 通过 `--c` 指定 c/c++ 格式化器，默认为 `clang-format-16`；
+- 通过 `--python` 指定 python 格式化器 `black`；
+
+### vscode 开发配置
+
+基本配置见 [xmake 官方文档](https://xmake.io/#/zh-cn/plugin/more_plugins?id=%e9%85%8d%e7%bd%ae-intellsence)。
+
+- TL;DR
+  - clangd
+
+    打开 *xmake.lua*，保存一次以触发编译命令生成，将在工作路径下自动生成 *.vscode/compile_commands.json* 文件。然后在这个文件夹下创建 *settings.json*，填入：
+
+    > .vscode/settings.json
+
+    ```json
+    {
+        "clangd.arguments": [
+            "--compile-commands-dir=.vscode"
+        ],
+        "xmake.additionalConfigArguments": [
+            // 在这里配置 XMAKE_CONFIG_FLAGS
+            "--nv-gpu=y"
+        ],
+    }
+    ```
--- a/README.md
+++ b/README.md
@@ -24,6 +24,8 @@ InfiniCore 是一个跨平台统一编程工具集，为不同芯片平台的功
 - 寒武纪 MLU；
 - 昆仑芯 XPU；

+API 定义以及使用方式详见 [`InfiniCore文档`](https://github.com/InfiniTensor/InfiniCore-Documentation)。
+
 ## 配置和使用

 ### 一键安装
@@ -129,62 +131,6 @@ xmake build infiniccl-test
 infiniccl-test --nvidia
 ```

-## 开发指南
-
-### 代码格式化
-
-本项目使用 [`scripts/format.py`](/scripts/format.py) 脚本实现代码格式化检查和操作。
-
-使用
-
-```shell
-python scripts/format.py -h
-```
-
-查看脚本帮助信息：
-
-```plaintext
-usage: format.py [-h] [--ref REF] [--path [PATH ...]] [--check] [--c C] [--py PY]
-
-options:
-  -h, --help         show this help message and exit
-  --ref REF          Git reference (commit hash) to compare against.
-  --path [PATH ...]  Files to format or check.
-  --check            Check files without modifying them.
-  --c C              C formatter (default: clang-format-16)
-  --py PY            Python formatter (default: black)
-```
-
-参数中：
-
- `ref` 和 `path` 控制格式化的文件范围
-  - 若 `ref` 和 `path` 都为空，格式化当前暂存（git added）的文件；
-  - 否则
-    - 若 `ref` 非空，将比较指定 commit 和当前代码的差异，只格式化修改过的文件；
-    - 若 `path` 非空，可传入多个路径（`--path p0 p1 p2`），只格式化指定路径及其子目录中的文件；
- 若设置 `--check`，将检查代码是否需要修改格式，不修改文件内容；
- 通过 `--c` 指定 c/c++ 格式化器，默认为 `clang-format-16`；
- 通过 `--python` 指定 python 格式化器 `black`；
-
-### vscode 开发配置
-
-基本配置见 [xmake 官方文档](https://xmake.io/#/zh-cn/plugin/more_plugins?id=%e9%85%8d%e7%bd%ae-intellsence)。
-
- TL;DR
-  - clangd
-
-    打开 *xmake.lua*，保存一次以触发编译命令生成，将在工作路径下自动生成 *.vscode/compile_commands.json* 文件。然后在这个文件夹下创建 *settings.json*，填入：
-
-    > .vscode/settings.json
+## 如何开源贡献

-    ```json
-    {
-        "clangd.arguments": [
-            "--compile-commands-dir=.vscode"
-        ],
-        "xmake.additionalConfigArguments": [
-            // 在这里配置 XMAKE_CONFIG_FLAGS
-            "--nv-gpu=y"
-        ],
-    }
-    ```
+见 [`InfiniCore开发者手册`](DEV.md)。
--- a/test/infiniop-test/README.md
+++ b/test/infiniop-test/README.md
@@ -65,11 +65,11 @@ Name: test.0.ans, NDims: 2, Shape: [6, 4], DataType: F64, DataOffset: 320
 - `Meta` 中必须包含 `test_count` ，表示测例数量。
 - 每个测例的 `Meta` 和 `Tensor` 名字以 `test.[id].` 开头，后接具体信息名称。数字 `[id]` 表示测例编号。编号必须为 0 到 test_count-1.
 - `Tensor` 名字接 `.strides` 表示步长，若没有则默认为连续。
+- 注意：gguf 中的 shape 和 stride 的存储方向是反向的，第一个数代表最后一维。

 ### GGUF测例构建要求

 不参与计算的 `Tensor` 不应存储数据，避免 `GGUF` 文件中出现冗余内容。
 此类 `Tensor` 应使用 `np.empty(tuple(0 for _ in shape), dtype=dtype)` 构造其数据字段,  且 `GGUF` 需存储此张量的形状数据 `.shape`、步长数据 `.strides`，否则无法成功构建，可使用 `contiguous_gguf_strides(shape)` 计算步长数据。

-
-对于 `Elementwise` 算子，需包含零步长（zero-stride）测试。对于步长为0的张量，`GGUF` 不应存储冗余广播数据，可使用 `process_zero_stride_tensor`进行冗余数据移除，同时必须在 `GGUF` 中提供此张量的实际形状数据 `.shape`，否则无法成功构建。
\ No newline at end of file
+对于 `Elementwise` 算子，需包含零步长（zero-stride）测试。对于步长为0的张量，`GGUF` 不应存储冗余广播数据，可使用 `process_zero_stride_tensor`进行冗余数据移除，同时必须在 `GGUF` 中提供此张量的实际形状数据 `.shape`，否则无法成功构建。