Merge pull request #555 from InfiniTensor/issue/554

文档更新： 更新InfiniCore开发指南

Author: PanZezhong1725

DEV.md

@@ -6,12 +6,12 @@ Dear 开发者，感谢你参与 InfiniCore 开源项目的开发！本文档将
 
 ### 项目模块体系
 
+- infinicore：统一计算框架。提供 Python 和 C++ 接口，支持多种硬件平台。
+- infinirt：统一底层运行时库，提供 C 语言接口，依赖 infini-utils。
+- infiniop：统一底层算子库，提供 C 语言接口，依赖 infinirt。除了 C++ 算子实现之外，也包括使用九齿（triton）的算子实现，这部分算子需要在编译之前使用脚本生成源文件。安装后可以运行位于 `test/infiniop` 中的单测脚本进行测试。
+- infiniccl：统一通信库，提供 C 语言接口，依赖 infinirt。
 - 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。
 
 ### 文件目录结构
@@ -21,10 +21,18 @@ Dear 开发者，感谢你参与 InfiniCore 开源项目的开发！本文档将
 ├── xmake/*.lua  # 各平台 xmake 编译配置， 包含各平台特有的编译方式
 │    
 ├── include/  # 对外暴露的头文件目录，安装时会被复制到安装目录
-│   ├── infiniop/*.h  # InfiniOP算子库子头文件
-│   ├── *.h  # 模块核心头文件
+│   ├── infinicore/*.hpp  # InfiniCore计算库头文件（C++）
+│   ├── infiniop/*.h  # InfiniOP算子库子头文件（C）
+│   ├── *.h/.hpp  # 模块核心头文件
 │ 
 ├── src/  # 各模块源代码目录，包含源代码文件以及不对外暴露的头文件
+│   ├── infinicore/ # InfiniCore源代码目录
+│   │   ├── context/  # 张量运行时/硬件上下文管理源代码目录
+│   │   ├── nn/  # 机器学习模块源代码目录
+│   │   ├── ops/  # 张量算子源代码目录
+│   │   ├── pybind/  # pybind 接口源代码目录
+│   │   ├── tensor/  # 张量库源代码目录
+│   │ 
 │   ├── infiniop/ # InfiniOP算子库源代码目录
 │   │   ├── devices/  # 每个设备平台各自的通用代码目录
 │   │   ├── ops/ # 算子实现代码目录
@@ -35,15 +43,14 @@ Dear 开发者，感谢你参与 InfiniCore 开源项目的开发！本文档将
 │   │   ├── elementwise/  # 逐元素类算子通用代码目录
 │   │   ├── *.h  # 核心结构体定义
 │   │
-│   ├── infiniop-test/  # InfiniOP算子库测试框架
 │   ├── infinirt/ # InfiniRT运行时库源代码目录
 │   ├── infiniccl/ # InfiniCCL集合通信库源代码目录
 │  
 ├── test/ # 测试源代码目录
+│   ├── infinicore/ # InfiniCore测试目录
+│   │       ├── ops/*.py     # 算子单测脚本（依赖各平台PyTorch）
 │   ├── infiniop/ # InfiniOP算子库单元测试目录
 │   │       ├── *.py     # 单测脚本（依赖各平台PyTorch）
-│   ├── infiniop-test/
-│   │       ├── test_generate/ # 算子库测试框架测例生成脚本
 │  
 ├── scripts/ # 脚本目录
 │   ├── install.py # 安装编译脚本
@@ -64,13 +71,7 @@ Dear 开发者，感谢你参与 InfiniCore 开源项目的开发！本文档将
 
 ### 如何开发一个新算子
 
-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++ 以及硬件原生语言开发一个新的算子，请阅读 [infinicore::ops 开发指南](/src/infinicore/ops/README.md)
 
 ### C++ 代码命名书写规范
 
@@ -138,6 +139,8 @@ Dear 开发者，感谢你参与 InfiniCore 开源项目的开发！本文档将
     int getMaxValue() const;
     ```
 
+    InfiniCore 中和 torch 对齐的接口，使用 `snake_case`。
+
 4. const/volatile修饰符写在类型前面
 
     ```c++

README.md

@@ -26,9 +26,17 @@ InfiniCore 是一个跨平台统一编程工具集，为不同芯片平台的功
 
 API 定义以及使用方式详见 [`InfiniCore文档`](https://github.com/InfiniTensor/InfiniCore-Documentation)。
 
+## 项目依赖
+
+- [Xmake](https://xmake.io/)：跨平台自动构建工具，用于编译 InfiniCore 项目。
+- [gcc-11](https://gcc.gnu.org/) 以上或者 [clang-16](https://clang.llvm.org/)：基础编译器，需要支持 C++ 17 标准。
+- [Python>=3.10](https://www.python.org/)
+  - [PyTorch](https://pytorch.org/)：可选，用于对比测试。
+- 各个硬件平台的工具包：请参考各厂商官方文档（如英伟达平台需要安装 CUDA Toolkit）。
+
 ## 配置和使用
 
-### 子模块
+### 一、克隆项目
 
 由于仓库中含有子模块，所以在克隆时请添加 `--recursive` 或 `--recurse-submodules`，如：
 
@@ -42,7 +50,27 @@ git clone --recursive https://github.com/InfiniTensor/InfiniCore.git
 git submodule update --init --recursive
 ```
 
-### 一键安装
+如果你需要在本地开发九齿算子（即需要对九齿算子库进行修改），推荐单独克隆[九齿算子库](https://github.com/InfiniTensor/ntops)，并从本地安装：
+
+```shell
+git clone https://github.com/InfiniTensor/ntops.git
+cd ntops
+pip install -e .
+```
+
+### 二、编译安装
+
+InfiniCore 项目主要包括：
+
+1. 底层 C 库（InfiniOP/InfiniRT/InfiniCCL）：[`一键安装`](#一键安装底层库)|[`手动安装`](#手动安装底层库)；
+2. InfiniCore C++ 库：[`安装指令`](#2-安装-c-库)
+3. InfiniCore Python 包（依赖[九齿算子库](https://github.com/InfiniTensor/ntops)）：[`安装指令`](#3-安装-python-包)
+
+三者需要按照顺序进行编译安装。
+
+#### 1. 安装底层库
+
+##### 一键安装底层库
 
 在 `script/` 目录中提供了 `install.py` 安装脚本。使用方式如下：
 
@@ -69,11 +97,17 @@ python scripts/install.py [XMAKE_CONFIG_FLAGS]
 | `--ninetoothed=[y\|n]`   | 是否编译九齿实现                 | n
 | `--ccl=[y\|n]`           | 是否编译 InfiniCCL 通信库接口实现 | n
 
-### 手动安装
+#####  手动安装底层库
 
 0. 生成九齿算子（可选）
 
-    参见[使用九齿](#使用九齿)章节。
+   - 克隆并安装[九齿算子库](https://github.com/InfiniTensor/ntops)。
+
+   - 在 `InfiniCore` 文件夹下运行以下命令 AOT 编译库中的九齿算子：
+
+     ```shell
+     PYTHONPATH=${PYTHONPATH}:src python scripts/build_ntops.py
+     ```
 
 1. 项目配置
 
@@ -118,91 +152,60 @@ python scripts/install.py [XMAKE_CONFIG_FLAGS]
 
    按输出提示设置 `INFINI_ROOT` 和 `LD_LIBRARY_PATH` 环境变量。
 
-### 运行测试
-
-#### 运行Python算子测试
+#### 2. 安装 C++ 库
 
 ```shell
-python test/infiniop/[operator].py [--cpu | --nvidia | --cambricon | --ascend]
-```
-
-#### 一键运行所有Python算子测试
-
-```shell
-python scripts/python_test.py [--cpu | --nvidia | --cambricon | --ascend]
+xmake build _infinicore
+xmake install _infinicore
 ```
 
-#### 算子测试框架
-
-详见 `test/infiniop-test` 目录
-
-#### 通信库（InfiniCCL）测试
-
-编译（需要先安装InfiniCCL）：
+#### 3. 安装 Python 包
 
 ```shell
-xmake build infiniccl-test
+pip install .
 ```
 
-在英伟达平台运行测试（会自动使用所有可见的卡）：
+或
 
 ```shell
-infiniccl-test --nvidia
+pip install . -e
 ```
 
-### `infinicore` Python 包
+注：开发时建议加入 `-e` 选项（即 `pip install -e .`），这样对 `python/infinicore` 做的更改将会实时得到反映，同时对 C++ 层所做的修改也只需要运行 `xmake build _infinicore && xmake install _infinicore` 便可以生效。
 
-#### 构建
+### 三、运行测试
 
-1. 进行[手动安装](#手动安装)。
-2. 构建与安装内部依赖库 `_infinicore`：
+#### 运行 InfiniCore Python算子接口测试
 
-```shell
-xmake build _infinicore
+```bash
+python test/infinicore/run.py --nvidia --verbose --bench
 ```
 
-#### 安装
+使用 -h 查看更多参数。
 
-1. 安装 `_infinicore`：
+#### 运行 InfiniOP 算子测试
 
 ```shell
-xmake install _infinicore
-```
-
-2. 安装 `infinicore`：
-
-```shell
-pip install .
+# 测试单算子
+python test/infiniop/[operator].py [--cpu | --nvidia | --cambricon | --ascend]
+# 测试全部算子
+python scripts/python_test.py [--cpu | --nvidia | --cambricon | --ascend]
 ```
 
-注：开发时建议加入 `-e` 选项（即 `pip install -e .`），这样对 `python/infinicore` 做的更改将会实时得到反映，同时对 C++ 层所做的修改也只需要运行 `xmake build _infinicore && xmake install _infinicore` 便可以生效。
-
-### 使用九齿
-
-[九齿](https://github.com/InfiniTensor/ninetoothed)是一门基于 Triton 但提供更高层抽象的领域特定语言（DSL）。使用九齿可以降低算子的开发门槛，并且提高开发效率。
-
-InfiniCore 目前已经可以接入使用九齿实现的算子，但是这部分实现的编译是默认关闭的。如果选择编译库中的九齿实现，需要使用 `--ninetoothed=y`，并在运行一键安装脚本前完成以下准备工作：
+#### 通信库（InfiniCCL）测试
 
-1. 安装九齿与[九齿算子库](https://github.com/InfiniTensor/ntops)：
+编译（需要先安装底层库中的 InfiniCCL 库）：
 
 ```shell
-git clone https://github.com/InfiniTensor/ntops.git
-cd ntops
-pip install -e .
+xmake build infiniccl-test
 ```
 
-注：安装 `ntops` 时，`ninetoothed` 会被当成依赖也一并安装进来。
-
-2. 在 `InfiniCore` 文件夹下运行以下命令 AOT 编译库中的九齿算子：
+在英伟达平台运行测试（会自动使用所有可见的卡）：
 
 ```shell
-PYTHONPATH=${PYTHONPATH}:src python scripts/build_ntops.py
+infiniccl-test --nvidia
 ```
 
-注：如果对九齿相关文件有修改，需要重新构建 InfiniCore 时，也需要同时运行以上命令进行重新生成。
-
-3. 按照上面的指引进行[一键安装](#一键安装)或者[手动安装](#手动安装)。
-
 ## 如何开源贡献
 
 见 [`InfiniCore开发者手册`](DEV.md)。