OpenCL介绍 on huluhuluu

Hello OpenCL

Wed, 01 Apr 2026 15:30:00 +0800

Hello OpenCL

这一篇文章的目标是用一个最小的 Vector Add 示例，串联起 OpenCL 的核心流程，运行环境：

platform：QUALCOMM Snapdragon(TM)
device：QUALCOMM Adreno(TM) 830
version：OpenCL 3.0 Adreno(TM) 830

1. 环境配置

宿主机需要编译环境，依赖c/cpp编译环境 + Opencl头文件 + 目标设备的动态库libOpenCL.so + Android交叉编译环境：

# 安装编译环境
sudo apt update & sudo apt upgrade
sudo apt install build-essential cmake -y

# 安装 OpenCL 头文件
# 这里不建议使用apt install opencl-headers 安装头文件
# 因为这个头文件会安装到系统目录/usr/include/CL/cl.h，交叉编译可能冲突
# 这里把 OpenCL-Headers 放到仓库里作为 submodule 管理
git submodule add https://github.com/KhronosGroup/OpenCL-Headers.git OpenCL-Headers
git submodule update --init --recursive
# 也可以直接克隆仓库 
# git clone https://github.com/KhronosGroup/OpenCL-Headers.git

# 获取目标设备的动态库
adb -s 127.0.0.1:40404 pull /vendor/lib64/libOpenCL.so OpenCL-Headers/

1.1 Android 交叉编译环境配置

如果还没有配置过 Android 交叉编译环境，需要先安装 Android NDK，配置环境变量。下面是一个示例流程：

步骤1：下载最新版软件包，获取地址（选择对应平台最新稳定版，点击后出现 “Android 软件开发套件许可协议”，勾选后鼠标右键下载按钮可以复制下载链接）

# 服务器端运行
# 到指定目录下载并解压 `android_ndk`
cd ~ && mkdir android_ndk && cd ~/android_ndk
wget https://googledownloads.cn/android/repository/android-ndk-r29-linux.zip
unzip android-ndk-r29-linux.zip # 这个文件名和下载的版本有关
# 删除压缩包
rm android-ndk-r29-linux.zip # 这个文件名和下载的版本有关

# 进入并记住解压后的目录
# 在目录里用 `pwd` 命令可以获取绝对路径
cd android-ndk-r29 # 这个目录和下载的版本有关，可以通过 `ls -lah` 显示目录

步骤2：配置环境变量

# 服务器端运行
# 通常会配置 `ANDROID_NDK_ROOT` 环境变量
# 但 `MNN` 中在 `project/android/build_64.sh` 使用的是 `$ANDROID_NDK` 环境变量，所以都设置一下
➜ export ANDROID_NDK="$HOME/android_ndk/android-ndk-r29" # 环境变量
➜ $ANDROID_NDK/ndk-build --version  # 验证环境变量
GNU Make 4.3
Built for x86_64-pc-linux-gnu
Copyright (C) 1988-2020 Free Software Foundation,  Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY,  to the extent permitted by law.

# 在命令行单次export只会在当前命令行有效 新开的终端不生效
# 需要把环境变量写到 `shell` 的配置文件中，`bash` 对应 `~/.bashrc`，`zsh` 对应 `~/.zshrc`
# !!注意这里重定向是重定向文件末尾 '>>' 符号
echo 'export ANDROID_NDK="$HOME/android_ndk/android-ndk-r29"' >> ~/.zshrc # 环境变量
echo 'export ANDROID_NDK_ROOT="$HOME/android_ndk/android-ndk-r29"'  >> ~/.zshrc # 环境变量
echo 'export PATH="$ANDROID_NDK:$PATH"' >> ~/.zshrc
# 验证
➜  ndk-build
Android NDK: Could not find application project directory !
Android NDK: Please define the NDK_PROJECT_PATH variable to point to it.
/root/android_ndk/android-ndk-r29/build/core/build-local.mk:151: *** Android NDK: Aborting    .  Stop.

2. 执行流程

这个最小示例的 Host 侧主线是：

枚举 platform / device
-> 创建 context
-> 创建 command queue
-> 读取 vector_add.cl
-> build program
-> 创建 kernel
-> 创建输入输出 buffer
-> 设置参数
-> enqueue NDRange
-> 读回输出并做 CPU 校验

2.1 初始化

首先做的是获取平台和设备，然后完成运行环境的构建。

核心流程是：

clGetPlatformIDs(0, nullptr, &platformCount); // 获取平台数量
clGetPlatformIDs(platformCount, platforms.data(), nullptr); // 选择平台
clGetDeviceIDs(platform, desiredType, 0, nullptr, &count); // 获取设备数量
clGetDeviceIDs(platform, desiredType, count, devices.data(), nullptr); // 选择设备
clCreateContext(nullptr, 1, &selection.device, nullptr, nullptr, &status); // 创建 context
clCreateCommandQueue(context.get(), selection.device, 0, &status); // 创建 command queue

2.2. 编译Kernel

示例 kernel 保持最小，每个work item都只计算：c[i] = a[i] + b[i]。

__kernel void vector_add(
    __global const float* a,
    __global const float* b,
    __global float* c,
    const unsigned int n) {
  const size_t id = get_global_id(0);
  if (id < n) {
    c[id] = a[id] + b[id];
  }
}

接着在代码中编译这个kernel:

1
2
3

clCreateProgramWithSource(context.get(), 1, &sourcePtr, &bytes, &status); // 创建 program
clBuildProgram(program.get(), 1, &selection.device, nullptr, nullptr, nullptr); // build program
clCreateKernel(program.get(), "vector_add", &status); // 获取 kernel

2.3 Buffer、参数绑定与执行

示例使用三块 buffer：

A：输入向量
B：输入向量
C：输出向量

Host 侧会先准备 CPU 数据和参考结果，然后走下面这条链：

// 创建 buffer 用于输入输出
clCreateBuffer(context.get(), CL_MEM_READ_ONLY, bufferSize, nullptr, &status); 
clCreateBuffer(context.get(), CL_MEM_READ_ONLY, bufferSize, nullptr, &status);
clCreateBuffer(context.get(), CL_MEM_WRITE_ONLY, bufferSize, nullptr, &status);
// 写入输入数据
clEnqueueWriteBuffer(queue.get(), bufferA.get(), CL_TRUE, 0, bufferSize,
                                     inputA.data(), 0, nullptr, nullptr);
clEnqueueWriteBuffer(queue.get(), bufferB.get(), CL_TRUE, 0, bufferSize,
                                     inputB.data(), 0, nullptr, nullptr);

// 设置 kernel 参数 这里参数对应上面kernel签名的顺序
clSetKernelArg(kernel.get(), 0, sizeof(bufferAHandle), &bufferAHandle);
clSetKernelArg(kernel.get(), 1, sizeof(bufferBHandle), &bufferBHandle);
clSetKernelArg(kernel.get(), 2, sizeof(bufferCHandle), &bufferCHandle);
clSetKernelArg(kernel.get(), 3, sizeof(elementCount), &elementCount);

// 定义 global size 和 local size， 这里需要是整数倍
clEnqueueNDRangeKernel(queue.get(), kernel.get(), 1, nullptr, &globalSize,
                        &localSize, 0, nullptr, nullptr);
// 等待 kernel 执行完成
clFinish(queue.get());

2.4 编译运行

要在Android上运行需要拉取目标设备的动态库，宿主机编译命令如下：

cmake -S . -B build \
  -DCMAKE_TOOLCHAIN_FILE="$ANDROID_NDK_ROOT/build/cmake/android.toolchain.cmake" \
  -DANDROID_ABI=arm64-v8a \
  -DANDROID_PLATFORM=android-29 \
  -DOPENCL_INCLUDE_DIR="$PWD/OpenCL-Headers" \
  -DOPENCL_LIBRARY="$PWD/OpenCL-Headers/libOpenCL.so"

cmake --build build -j4 --target opencl_vector_add

支持额外参数：

--count <N>：设置向量长度
--local <N>：设置本次运行的 local size

export OPENCL_DEMO_DIR=/data/local/tmp/opencl_vector_add

adb -s 127.0.0.1:40404 shell "mkdir -p $OPENCL_DEMO_DIR"
adb -s 127.0.0.1:40404 push \
  build/opencl_vector_add \
  build/vector_add.cl \
  /tmp/opencl-android/lib/arm64-v8a/libOpenCL.so \
  "$ANDROID_NDK_ROOT/toolchains/llvm/prebuilt/linux-x86_64/sysroot/usr/lib/aarch64-linux-android/libc++_shared.so" \
  "$OPENCL_DEMO_DIR/"

adb -s 127.0.0.1:40404 shell "
  cd $OPENCL_DEMO_DIR && \
  export LD_LIBRARY_PATH=$OPENCL_DEMO_DIR && \
  ./opencl_vector_add --kernel ./vector_add.cl --count 1024 --local 64
"

这次实测输出为：

OpenCL vector add example
kernel_path : ./vector_add.cl
platform    : QUALCOMM Snapdragon(TM)
device      : QUALCOMM Adreno(TM) 830
device_type : GPU
device_ver  : OpenCL 3.0 Adreno(TM) 830
shape       : 1024 elements
global_size : 1024
local_size  : 64
max_abs_err : 0.000000
mean_abs_err: 0.000000
validation  : PASS
output[0:8] : -4.021429 -3.678571 -3.335714 -2.992857 -2.650000 -2.307143 -1.964286 -1.621428

CPU Baseline
stage                           time(us)
----------------------------------------
cpu_vector_add                         4

OpenCL Time Breakdown
stage                           time(us)
----------------------------------------
read_kernel_source                    41
enumerate_platforms                30794
load_platform_list                     0
select_device                          3
create_context                      2135
create_queue                           1
create_program                         3
build_program                      15383
create_kernel                          2
query_work_group                       1
create_buffer_a                        9
create_buffer_b                        3
create_buffer_c                        4
write_input_a                          7
write_input_b                          1
set_kernel_args                        2
enqueue_kernel                      8798
read_output                           24

Accuracy Comparison
cpu_reference        : fp32 vector add
opencl_vs_cpu_maxerr : 0.000000
opencl_vs_cpu_meanerr: 0.000000

Performance Comparison
cpu_baseline_us        : 4
opencl_kernel_us       : 8798
opencl_end_to_end_us   : 57211
kernel_speedup_vs_cpu  : 0.000455x
end_to_end_speedup_cpu : 0.000070x

2.5 向量类型

opencl 还内置了向量类型，支持 $N=\{2,3,4,8,16\}$ 的大小。使用向量类型可以让每个 work item 处理更多数据，并且提供类似的广播机制，如下图所示。 图 1. 当标量 x 被显式转成 float4 时，会按 (x, x, x, x) 的形式广播，再与 float4 y 做逐元素计算。

OpenCL 介绍

Wed, 01 Apr 2026 15:00:00 +0800

OpenCL 介绍与执行流程

博客目标是梳理 OpenCL 的核心概念和执行流程，包括

Host 和 Device 分别负责什么。
Platform / Context / Queue / Program / Kernel 链路。
NDRange / work-item / work-group 关系。
global / local / private 内存层次。

1. OpenCL

OpenCL（Open Computing Language）是 Khronos 定义的异构计算标准。它试图提供一套统一的主机侧 API，让应用能够同时把并行计算任务提交给不同类型的设备，例如：CPU、GPU、DSP、FPGA、其他专用加速器等，可以执行跨异构平台的程序。

可以把 OpenCL 理解成两层：

上层是 Host 侧 API，用来枚举设备、创建上下文、提交命令。
下层是运行时和驱动，实现真正的 Device 上的 kernel 编译与执行。

不同厂商的设备提供的运行时和驱动由各厂商自己编写，但都遵守 Khronos 定义的 OpenCL 规范，结构如下图。 图 1. OpenCL 软件栈与 Host、Device 的关系示意。

2. 执行流程

2.1 OpenCL 执行流程

执行 OpenCL 程序的大致流程如下图，划分三个阶段：编译，资源准备，执行。 图 2. OpenCL 程序从编译、资源准备到执行的流程示意。

具体来说，包括以下步骤：

枚举 platform
-> 选择 device
-> 创建 context
-> 创建 command queue
-> 读取 kernel 源码
-> 创建并 build program
-> 创建 kernel
-> 创建 buffer
-> 写入输入
-> 设置 kernel 参数
-> enqueue NDRange
-> 读回输出

2.2 对象概念

OpenCL 主要包括以下几个核心对象：

Context：设备资源的宿主，大多数内存对象、程序对象和 kernel 生命周期都依附在 Context 上。
Command Queue：负责把命令提交给设备，常见命令包括 buffer 拷贝、kernel 启动、同步等待。
Program：对应 OpenCL C 源码或者预编译二进制。
Kernel：是从 Program 中取出的一个可执行入口。
Buffer / Image：内存对象，代表设备上的数据存储。

3. OpenCL 平台模型

OpenCL 平台模型描述了 OpenCL 如何理解要拓扑连接的系统中的计算资源，参考下图： 图 3. OpenCL 平台模型中 Host、Device、compute unit 与处理元件的关系示意。

主机（Host）连接到一个或多个 OpenCL 计算设备。每个计算设备（Device）是一个或多个计算单元的集合，其中每个计算单元由一个或更多个处理元件组成。

在 Android 场景里，常见的情况是：

Host 代码跑在 CPU 上，负责准备输入数据、创建 OpenCL 对象、提交命令和读取输出结果。
运行时来自厂商提供的 libOpenCL.so，例如SnapDragon 8 elite的/vendor/lib64/libOpenCL.so
Device 是手机上的 Adreno 或 Mali GPU，是真正执行 kernel 的设备

4. OpenCL 执行模型

OpenCL 的执行模型，是一个基于 NDRange 的数据并行模型。主机侧通过 clEnqueueNDRangeKernel 命令，把同一个 kernel 入口在一个 N 维索引空间上并行启动。这个索引空间就叫 NDRange，可以是一维、二维或三维。

以二维图像举例，如下图：

整张图像的宽和高，构成这次执行的 NDRange
图像中的每一个像素，可以看成一个 work-item
每个 work-item 都会执行同一份 kernel 代码，只是通过自己的索引访问不同的数据位置

图 4. OpenCL 执行模型中 NDRange、work-item 和 work-group 的关系示意。

从硬件角度看，处理器通常不会把所有处理元件平铺成一个大集合，而是会先把它们组织成一个个 compute unit。这样可以提高调度效率和资源利用率，设计局部共享资源。因此，OpenCL把一批连续的 work-item 分成一个组:

work-item：最小执行单位，对应一次 kernel 副本
work-group：一组可以协同工作的 work-item，大小是work-group size
compute unit：设备上负责调度和执行一个或多个 work-group 的硬件执行单元

同一个 work-group 内的 work-item 具备：

共享 local memory
通过 work-group barrier 做组内同步
使用 async_work_group_copy 这类 work-group 级函数高效搬运数据

而不同 work-group 之间更加独立，通常通过 global memory 间接通信。所以，opencl先定义数据空间，再把空间里的每个元素映射成 work-item，最后根据硬件特性决定 work-group size。

例如一个三维数据大小是 (2, 2, 8)，按照 (2, 2, 2) 的 work-group size 来执行，那么就会有 4 个 work-group，每个 work-group 里有 8 个 work-item，总共 32 个 work-item 来处理这 32 个数据元素。 图 5. 一个 (2, 2, 8) 的 NDRange 按 (2, 2, 2) 的 work-group size 切分后的分组示意。

5. 内存模型

OpenCL 有一个内存类型的层次结构，不同内存都不会自动同步，需要在内存类型之间显式移动数据，如图 图 6. OpenCL 内存层次结构示意。 其中，

主机内存：可供主机CPU使用
全局/常量内存：可用于计算设备中的所有计算单元
本地内存：可供计算单元中的所有处理单元使用
专用内存：可供单个处理单元使用

OpenCL介绍 on huluhuluu

Hello OpenCL

Hello OpenCL

1. 环境配置

1.1 Android 交叉编译环境配置

2. 执行流程

2.1 初始化

2.2. 编译Kernel

2.3 Buffer、参数绑定与执行

2.4 编译运行

2.5 向量类型

OpenCL 介绍

OpenCL 介绍与执行流程

1. OpenCL

2. 执行流程

2.1 OpenCL 执行流程

2.2 对象概念

3. OpenCL 平台模型

4. OpenCL 执行模型

5. 内存模型

6. 参考资料