# arenocl

**Repository Path**: techwolf/arenocl

## Basic Information

- **Project Name**: arenocl
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-10
- **Last Updated**: 2026-02-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Adreno GPU ONNX Inference Acceleration

在 Windows ARM 平台上使用 Qualcomm Adreno GPU 进行 ONNX 深度学习模型推理加速的高性能 OpenCL 程序。

## 项目简介

本项目为 Windows on ARM 设备（如 Snapdragon X Elite、Snapdragon X Plus 等）提供 ONNX 模型推理加速，通过 OpenCL 充分利用 Adreno GPU 的并行计算能力，实现高效的深度学习推理。

### 主要特性

- ✅ 支持 Windows ARM64 原生编译和运行
- ✅ 针对 Qualcomm Adreno GPU 优化的 OpenCL 内核
- ✅ 支持常见深度学习操作（卷积、池化、全连接、激活函数等）
- ✅ 高效的内存管理和数据传输
- ✅ 内置性能统计和基准测试功能
- ✅ 简单易用的命令行接口

### 支持的操作

- **卷积层**: Conv2D, Depthwise Conv2D
- **池化层**: MaxPool2D, AvgPool2D, GlobalAvgPool
- **激活函数**: ReLU, Leaky ReLU, Sigmoid, Tanh, Swish, ELU, GELU
- **全连接层**: GEMM (矩阵乘法)
- **归一化**: Batch Normalization
- **元素操作**: Add, Multiply, Scale & Shift
- **其他**: Flatten, Concat, Transpose, Reshape, Softmax

## 系统要求

### 硬件要求

- **处理器**: Qualcomm Snapdragon X Elite, Snapdragon X Plus 或其他 ARM64 处理器
- **GPU**: 集成 Adreno GPU（与 Snapdragon 处理器配套）
- **内存**: 至少 4GB RAM（建议 8GB 以上）
- **存储**: 至少 500MB 可用空间

### 软件要求

- **操作系统**: Windows 10 或 Windows 11 (ARM64)
- **Visual Studio 2022**: 包含 C++ 和 ARM64 构建工具
- **LLVM/Clang**: **必需**用于 ARM64 编译（llama.cpp 依赖要求）
- **CMake**: 3.10 或更高版本
- **Qualcomm Adreno GPU SDK**: 包含 OpenCL 头文件和运行时

详细安装说明请参阅 [BUILD.md](BUILD.md)。

## 快速开始

### 1. 安装依赖

安装以下软件：
- Visual Studio 2022（包含 ARM64 构建工具）
- CMake
- Qualcomm Adreno GPU SDK

设置环境变量：
```powershell
setx ADRENO_SDK_PATH "C:\opencl-sdk" /M
```

### 2. 构建项目

**方法一：使用构建子目录（推荐）**

```powershell
# 导航到项目根目录（包含 CMakeLists.txt 的目录）
cd C:\Users\13911\Desktop\git\ocl

# 创建并进入构建目录
mkdir build
cd build

# 配置项目（自动检测 Visual Studio，原生 ARM64 构建）
# 注意：".." 指向包含 CMakeLists.txt 的父目录
cmake .. -A ARM64

# 构建项目
cmake --build . --config Release
```

**方法二：使用 -B 标志（备选）**

```powershell
# 导航到项目根目录
cd C:\Users\13911\Desktop\git\ocl

# 直接从项目根目录配置和构建
cmake -B build -A ARM64
cmake --build build --config Release
```

**重要提示：**
- 务必从项目根目录（CMakeLists.txt 所在目录）运行 CMake
- 使用方法一时，在 build 目录内运行 `cmake ..`
- 使用方法二时，从项目根目录运行 `cmake -B build`
- 如果出现"source directory does not appear to contain CMakeLists.txt"错误，说明当前目录不正确

**指定 Visual Studio 版本（可选）：**

```powershell
# 检查已安装的 Visual Studio 版本
cmake --help

# 使用特定版本
cmake .. -G "Visual Studio 17 2022" -A ARM64
cmake .. -G "Visual Studio 16 2019" -A ARM64
```

详细构建说明和故障排除请参阅 [BUILD.md](BUILD.md)。

### 3. 运行示例

```powershell
cd build\bin\Release

# 查看帮助
adreno_onnx_inference.exe --help

# 使用基准测试模式运行（使用内置演示模型）
adreno_onnx_inference.exe --model dummy.onnx --benchmark --iterations 10
```

## 使用方法

### 基本用法

```powershell
adreno_onnx_inference.exe --model model.onnx --input input.bin --output output.bin
```

### 命令行参数

| 参数 | 说明 | 必需 |
|------|------|------|
| `--model <path>` | ONNX 模型文件路径 | 是 |
| `--input <path>` | 输入数据文件路径（二进制 float32） | 否 |
| `--output <path>` | 输出数据保存路径（二进制 float32） | 否 |
| `--iterations <n>` | 推理迭代次数（默认: 1） | 否 |
| `--benchmark` | 基准测试模式（不保存输出） | 否 |
| `--help` | 显示帮助信息 | 否 |

### 示例

#### 1. 单次推理

```powershell
adreno_onnx_inference.exe --model resnet50.onnx --input image_data.bin --output predictions.bin
```

#### 2. 基准测试

```powershell
adreno_onnx_inference.exe --model mobilenet_v2.onnx --benchmark --iterations 100
```

#### 3. 使用随机输入测试

```powershell
# 不提供输入文件时，会自动生成随机数据
adreno_onnx_inference.exe --model my_model.onnx --output result.bin
```

## 项目结构

```
ocl/
├── include/              # 头文件
│   ├── opencl_device.h          # OpenCL 设备管理
│   ├── opencl_kernel.h          # OpenCL 内核管理
│   ├── onnx_model_loader.h      # ONNX 模型加载器
│   └── inference_engine.h       # 推理引擎
├── src/                 # 源文件
│   ├── opencl_device.cpp
│   ├── opencl_kernel.cpp
│   ├── onnx_model_loader.cpp
│   ├── inference_engine.cpp
│   └── main.cpp                # 主程序
├── kernels/             # OpenCL 内核文件
│   ├── activation_kernels.cl   # 激活函数内核
│   ├── conv_pool_kernels.cl    # 卷积和池化内核
│   └── common_kernels.cl      # 通用操作内核
├── models/              # 模型文件目录
├── BUILD.md            # 详细构建说明
├── README.md           # 本文件
├── CMakeLists.txt      # CMake 构建配置
└── .gitignore          # Git 忽略文件
```

## 性能优化建议

### 1. 使用原生 ARM64 构建

在 ARM64 设备上，原生 ARM64 构建比 x64 构建（通过模拟运行）性能提升显著：

```powershell
# 推荐：原生 ARM64 构建（自动检测 Visual Studio）
cmake .. -A ARM64

# 或指定 Visual Studio 版本
cmake .. -G "Visual Studio 17 2022" -A ARM64

# 不推荐：x64 构建（会通过模拟运行）
cmake .. -A x64
```

### 2. 使用 Release 配置

```powershell
cmake --build . --config Release
```

### 3. GPU 性能设置

- 在设备设置中启用 GPU 性能模式
- 确保设备保持良好的散热
- 关闭不必要的后台应用以释放 GPU 资源

### 4. 内存优化

- 对于大型模型，考虑使用批处理推理以提高 GPU 利用率
- 尽量减少主机和设备之间的数据传输

## 性能基准

在 Snapdragon X Elite 设备上的典型性能（原生 ARM64 构建）：

| 模型 | 推理时间 | 吞吐量 |
|------|----------|--------|
| MobileNetV2 | ~15ms | ~66 FPS |
| ResNet-50 | ~45ms | ~22 FPS |
| EfficientNet-B0 | ~35ms | ~28 FPS |

*注：实际性能取决于具体硬件配置和模型复杂度*

## 故障排除

### 常见问题

**Q: 编译时提示找不到 OpenCL 头文件**

A: 确保已安装 Adreno SDK 并设置了 ADRENO_SDK_PATH 环境变量。

**Q: 运行时检测不到 Adreno GPU**

A: 检查设备是否安装了最新的 GPU 驱动，确认设备具有 Adreno GPU。

**Q: 推理速度比预期慢**

A: 
- 确认使用的是原生 ARM64 构建
- 使用 Release 配置
- 检查设备散热和电源设置

更多故障排除信息请参阅 [BUILD.md](BUILD.md)。

## 技术架构

### OpenCL 设备管理
- 自动检测和初始化 Adreno GPU
- 设备信息查询和验证
- 内存缓冲区管理

### 内核编译和执行
- JIT 编译 OpenCL 内核
- 高效的任务调度
- 内存优化和数据局部性

### 推理管道
1. 加载 ONNX 模型
2. 编译所需的 OpenCL 内核
3. 上传输入数据到 GPU
4. 按顺序执行模型操作
5. 下载输出数据到 CPU

## 开发路线图

- [ ] 完整的 ONNX Runtime 集成
- [ ] 支持 FP16 推理以提高速度
- [ ] 批处理推理支持
- [ ] 动态批处理
- [ ] 更多优化技术（内核融合、量化等）
- [ ] 图形界面

## 贡献指南

欢迎贡献！请遵循以下步骤：

1. Fork 本项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 许可证

本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。

## 致谢

- Qualcomm Adreno GPU SDK
- Khronos OpenCL
- ONNX 社区

## 相关资源

- [Qualcomm Developer Network](https://developer.qualcomm.com/)
- [Adreno GPU SDK](https://developer.qualcomm.com/software/adreno-gpu-sdk)
- [OpenCL 规范](https://www.khronos.org/opencl/)
- [ONNX 官网](https://onnx.ai/)
- [Windows on ARM 文档](https://learn.microsoft.com/en-us/windows/arm/)

## 联系方式

如有问题或建议，请：
- 提交 Issue
- 发送邮件至项目维护者

---

**注意**: 本项目为教育和研究目的提供。在生产环境中使用前，请进行充分的测试和验证。