Skip to content

add doc #15

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
BingooYang merged 8 commits into from
Feb 3, 2026
Merged

add doc #15

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
d829981
add doc
youge325 Jan 5, 2026
6a57309
Update doc/tensor_base.md
youge325 Jan 6, 2026
e2e8647
add allocator、layout and storage docs
youge325 Jan 7, 2026
7875726
update doc
youge325 Jan 11, 2026
9a8c8cf
update doc
youge325 Jan 11, 2026
0c0d9e6
update
youge325 Jan 16, 2026
49f5c84
update
youge325 Jan 22, 2026
02c8d44
update
youge325 Jan 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
131 changes: 131 additions & 0 deletions doc/allocator.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,131 @@
##### Allocator.h 头文件 API 兼容情况


##### Allocator.h 头文件 API 兼容性

✅ 表示已经支持
🚧 表示正在支持
❌ 表示不准备支持
🔧 表示部分支持（有功能限制）

**按照功能分类排序**

---

### 类型定义

| torch API | paddle API 兼容性 | 测试用例状态 | 优先级 | 备注 |
|------------------------------|------------------|------------|-------|------|
| `DeleterFnPtr` | ✅ | ✅ | P0 | 删除器函数指针类型 |

---

### DataPtr 类

#### 构造与赋值

| torch API | paddle API 兼容性 | 测试用例状态 | 优先级 | 备注 |
|------------------------------|------------------|------------|-------|------|
| `DataPtr()` | ✅ | ✅ | P0 | 默认构造函数 |
| `DataPtr(void*, Device)` | ✅ | ✅ | P0 | 数据指针+设备构造 |
| `DataPtr(void*, void*, DeleterFnPtr, Device)` | ✅ | ✅ | P0 | 完整构造函数 |
| `DataPtr(const DataPtr&)` | ✅ | ✅ | P0 | 拷贝构造函数 |
| `DataPtr(DataPtr&&)` | ✅ | ✅ | P0 | 移动构造函数 |
| `operator=(const DataPtr&)` | ✅ | ✅ | P0 | 拷贝赋值运算符 |
| `operator=(DataPtr&&)` | ✅ | ✅ | P0 | 移动赋值运算符 |

#### 数据访问 API

| torch API | paddle API 兼容性 | 测试用例状态 | 优先级 | 备注 |
|------------------------------|------------------|------------|-------|------|
| `get()` | ✅ | ✅ | P0 | 获取原始指针 |
| `operator->()` | ✅ | ✅ | P0 | 指针访问运算符 |
| `operator bool()` | ✅ | ✅ | P0 | 布尔转换 |
| `device()` | ✅ | ✅ | P0 | 获取设备 |
| `get_deleter()` | ✅ | ✅ | P1 | 获取删除器 |
| `get_context()` | ✅ | ✅ | P1 | 获取上下文 |
| `clear()` | ✅ | ✅ | P1 | 清空数据 |
| `mutable_get()` | - [ ] | - [ ] | P2 | 获取可变指针 |
| `release_context()` | - [ ] | - [ ] | P2 | 释放上下文 |
| `move_context()` | - [ ] | - [ ] | P2 | 移动上下文 |
| `compare_exchange_deleter()` | - [ ] | - [ ] | P3 | 比较交换删除器 |
| `unsafe_set_device()` | - [ ] | - [ ] | P3 | 不安全设置设备 |

#### 比较运算符

| torch API | paddle API 兼容性 | 测试用例状态 | 优先级 | 备注 |
|------------------------------|------------------|------------|-------|------|
| `operator==(DataPtr, nullptr_t)` | ✅ | ✅ | P0 | |
| `operator==(nullptr_t, DataPtr)` | ✅ | ✅ | P0 | |
| `operator!=(DataPtr, nullptr_t)` | ✅ | ✅ | P0 | |
| `operator!=(nullptr_t, DataPtr)` | ✅ | ✅ | P0 | |

---

### Allocator 基类

| torch API | paddle API 兼容性 | 测试用例状态 | 优先级 | 备注 |
|------------------------------|------------------|------------|-------|------|
| `allocate(size_t)` | - [ ] | - [ ] | P2 | 分配内存 |
| `clone(void*, size_t)` | - [ ] | - [ ] | P3 | 克隆分配 |
| `is_simple_data_ptr()` | - [ ] | - [ ] | P3 | |
| `raw_deleter()` | - [ ] | - [ ] | P2 | 获取原始删除器 |
| `raw_allocate(size_t)` | - [ ] | - [ ] | P2 | 原始分配 |
| `raw_deallocate(void*)` | - [ ] | - [ ] | P2 | 原始释放 |
| `copy_data()` | - [ ] | - [ ] | P3 | 复制数据 |

---

### 全局函数

| torch API | paddle API 兼容性 | 测试用例状态 | 优先级 | 备注 |
|------------------------------|------------------|------------|-------|------|
| `SetAllocator()` | - [ ] | - [ ] | P3 | 设置分配器 |
| `GetAllocator()` | - [ ] | - [ ] | P3 | 获取分配器 |

---

### InefficientStdFunctionContext

| torch API | paddle API 兼容性 | 测试用例状态 | 优先级 | 备注 |
|------------------------------|------------------|------------|-------|------|
| `makeDataPtr()` | - [ ] | - [ ] | P3 | 创建带自定义删除器的 DataPtr |

---

### Paddle 兼容层特有 API

| API | 说明 |
|------------------------------|------|
| `DataPtr(shared_ptr<phi::Allocation>)` | 从 Paddle Allocation 构造 |
| `allocation()` | 获取底层 phi::Allocation |

---

### 兼容性统计

| 状态 | 数量 |
|------|------|
| ✅ 已完全支持 | 18 |
| 🚧 正在支持 | 0 |
| 🔧 部分支持 | 0 |
| - [ ] 未实现 | 12 |

---

### 备注

1. **优先级说明**：
- P0: 核心功能，必须支持
- P1: 常用功能，高优先级
- P2: 进阶功能，中优先级
- P3: 边缘功能，低优先级

2. **实现说明**：
- Paddle 兼容层的 `DataPtr` 基于 `phi::Allocation` 实现
- 设备类型使用 `phi::Place` 而非 `c10::Device`
- `Allocator` 基类暂未实现，使用 Paddle 原生的 `phi::Allocator`

3. **命名空间**：
- `c10::DataPtr` - 主命名空间
- `at::DataPtr` - 别名
91 changes: 91 additions & 0 deletions doc/layout.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
##### Layout.h 头文件 API 兼容情况


##### Layout.h 头文件 API 兼容性

✅ 表示已经支持
🚧 表示正在支持
❌ 表示不准备支持
🔧 表示部分支持（有功能限制）

**按照功能分类排序**

---

### Layout 枚举类型

| torch API | paddle API 兼容性 | 测试用例状态 | 优先级 | 备注 |
|------------------------------|------------------|------------|-------|------|
| `Layout::Strided` | ✅ | ✅ | P0 | 标准密集布局 |
| `Layout::Sparse` | ✅ | ✅ | P2 | COO 稀疏布局 |
| `Layout::SparseCsr` | ✅ | ✅ | P2 | CSR 稀疏布局 |
| `Layout::Mkldnn` | ✅ | ✅ | P3 | MKLDNN 布局 |
| `Layout::SparseCsc` | ✅ | ✅ | P3 | CSC 稀疏布局 |
| `Layout::SparseBsr` | ✅ | ✅ | P3 | BSR 稀疏布局 |
| `Layout::SparseBsc` | ✅ | ✅ | P3 | BSC 稀疏布局 |
| `Layout::Jagged` | ✅ | ✅ | P3 | 不规则布局 |
| `Layout::NumOptions` | ✅ | ✅ | P3 | 布局选项数量 |

---

### 布局常量

| torch API | paddle API 兼容性 | 测试用例状态 | 优先级 | 备注 |
|------------------------------|------------------|------------|-------|------|
| `kStrided` | ✅ | ✅ | P0 | = Layout::Strided |
| `kSparse` | ✅ | ✅ | P2 | = Layout::Sparse |
| `kSparseCsr` | ✅ | ✅ | P2 | = Layout::SparseCsr |
| `kMkldnn` | ✅ | ✅ | P3 | = Layout::Mkldnn |
| `kSparseCsc` | ✅ | ✅ | P3 | = Layout::SparseCsc |
| `kSparseBsr` | ✅ | ✅ | P3 | = Layout::SparseBsr |
| `kSparseBsc` | ✅ | ✅ | P3 | = Layout::SparseBsc |
| `kJagged` | ✅ | ✅ | P3 | = Layout::Jagged |

---

### 辅助函数

| torch API | paddle API 兼容性 | 测试用例状态 | 优先级 | 备注 |
|------------------------------|------------------|------------|-------|------|
| `operator<<(ostream, Layout)` | ✅ | ✅ | P1 | 输出流运算符 |
| `layout_from_backend()` | - [ ] | - [ ] | P3 | 从后端推断布局 |

---

### 命名空间导出

| 命名空间 | 导出内容 | 状态 |
|---------|---------|------|
| `c10` | Layout 枚举、所有常量 | ✅ |
| `at` | Layout 枚举、所有常量 | ✅ |
| `torch` | Layout 枚举、所有常量 | ✅ |

---

### 兼容性统计

| 状态 | 数量 |
|------|------|
| ✅ 已完全支持 | 18 |
| 🚧 正在支持 | 0 |
| 🔧 部分支持 | 0 |
| - [ ] 未实现 | 1 |

---

### 备注

1. **优先级说明**：
- P0: 核心功能，必须支持
- P1: 常用功能，高优先级
- P2: 进阶功能，中优先级
- P3: 边缘功能，低优先级

2. **实现说明**：
- Layout 枚举与 LibTorch 完全一致
- 输出流运算符支持所有布局类型的字符串表示
- `layout_from_backend()` 未实现，因为 Paddle 使用不同的后端抽象

3. **使用建议**：
- 大多数场景使用 `kStrided`（默认密集布局）
- 稀疏张量相关布局需要配合稀疏张量 API 使用
Loading