# vulkan-compute-samples

**Repository Path**: brt2/vulkan-compute-samples

## Basic Information

- **Project Name**: vulkan-compute-samples
- **Description**: MiniMax 实现的demo示例集
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-28
- **Last Updated**: 2026-06-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# vulkan-test · Vulkan Compute Pipeline 教程

一份跑在 Termux + 高通骁龙（Adreno 644 / Turnip）上的 Vulkan
compute pipeline 教程。9 个 demo，每个只引入一个新 Vulkan 概念。
所有 demo 都针对真 GPU（Turnip）跑通；如果你的设备不一样，
fallback 策略在每个 demo 的 README 里写明。

## 学习路径

如果你是第一次接触 Vulkan compute，建议按 1 → 2 → ... → 9 顺序读。
每一个 demo 都会在前一个 demo 的基础上**只加一个新概念**（barrier
→ shared memory → multi-buffer → specialization → push descriptor
→ subgroup → timeline → 综合），不会一次性把所有特性塞进来。

如果只想看某个具体概念，直接跳到对应章节即可——每个 demo 都能
独立编译、运行。

## 章节索引

| # | 目录 | 新概念 | 验证 |
|---|---|---|---|
| 1 | [01-base-compute-pipeline](demos/01-base-compute-pipeline/README.md) | 整个 baseline：instance → device → SPIR-V → SSBO → dispatch → 读回 | `out[i] == (magic<<16) \| i` |
| 2 | [02-multiple-dispatches-and-barriers](demos/02-multiple-dispatches-and-barriers/README.md) | 单 command buffer 内两个 dispatch + `vkCmdPipelineBarrier` | `values[i] == i+1` |
| 3 | [03-shared-memory-reduction](demos/03-shared-memory-reduction/README.md) | workgroup-local shared memory + `barrier()` butterfly 规约 | 4 个 workgroup 输出 = 各分组和 |
| 4 | [04-multi-buffer-descriptor-array](demos/04-multi-buffer-descriptor-array/README.md) | 描述符集绑定 3 个 SSBO，shader 端按 binding 索引 | `out[i] = A[i] + B[i]` |
| 5 | [05-specialization-constants](demos/05-specialization-constants/README.md) | `VkSpecializationInfo` 传递编译期常量 | 两个 bound 各自对应累加和 |
| 6 | [06-push-descriptors](demos/06-push-descriptors/README.md) | `VK_KHR_push_descriptor` 跳过 pool，inline 写 descriptor | `out[i] == in[i]`（不支持时 skip） |
| 7 | [07-subgroups](demos/07-subgroups/README.md) | `gl_NumSubgroups`、`subgroupAdd`、`subgroupBroadcast` | `subgroupAdd(i)` 与按 `subgroupSize` 划分的预期值匹配 |
| 8 | [08-async-compute-and-timeline-semaphores](demos/08-async-compute-and-timeline-semaphores/README.md) | `VK_KHR_timeline_semaphore`（1.2 core）跨 submit 同步 | `B[0] == sum(0..255) == 32640` |
| 9 | [09-mini-gemm-capstone](demos/09-mini-gemm-capstone/README.md) | 综合 demo2~8：多 dispatch + barrier + shared + push + subgroup | 32×32 整数 GEMM 与 reference 完全一致 |

> demo6 和 demo9 用到 `VK_KHR_push_descriptor`。在 Turnip 上 instance
> 层不一定暴露该扩展，demo6 选择 graceful skip（exit 0），demo9
> 回退到普通 descriptor set 继续跑。两条路径都不会让 ctest 失败。

## 需要的 Termux 包

```sh
pkg install shaderc vulkan-headers spirv-headers cmake
```

`shaderc` 顺带拉入 `glslang`（提供 `glslangValidator`）和
`spirv-tools`。Vulkan loader 与 Turnip ICD 在设备上已自带。

## 构建与运行

```sh
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j
ctest --test-dir build --output-on-failure
```

期望：

```
100% tests passed, 0 tests failed out of 9
```

单独跑某个 demo：

```sh
cmake --build build --target run-demo1
./build/demos/01-base-compute-pipeline/demo1
```

或直接用 ctest 跑单个：

```sh
ctest --test-dir build -R '^demo5$' --output-on-failure
```

清理：

```sh
rm -rf build
```

## 文件结构

```
.
├── CMakeLists.txt             # 顶层：find_package(Vulkan) + add_subdirectory 每个 demo
├── cmake/DemoHelper.cmake     # vulkan_add_demo() / vulkan_add_shader()
├── README.md                  # 本文件（教程总览）
├── CLAUDE.md                  # 踩坑 + 环境 + 如何新增 demo
└── demos/                     # 9 个 demo 子目录
    ├── 01-base-compute-pipeline/
    ├── 02-multiple-dispatches-and-barriers/
    ├── ...
    └── 09-mini-gemm-capstone/
```

每个 demo 目录自包含：

```
demos/0N-xxx/
├── CMakeLists.txt
├── README.md
├── src/main.c
└── shaders/*.comp
```

## 运行环境（验证于 2026-06-27）

- **宿主机**：Termux on Android，内核 5.10，`aarch64-unknown-linux-android24`
- **编译器**：clang 21.1.8（也自带 gcc）
- **Vulkan loader**：`$PREFIX/lib/libvulkan.so.1.4.355`
- **ICD #1**：`libvulkan_freedreno.so` → **Turnip Adreno (TM) 644**
  （Qualcomm 厂商 `0x5143`，设备 `0x6060201`，Vulkan 1.3）
- **ICD #2**：`libvulkan_lvp.so` → llvmpipe（软件兜底）

## 阅读每个 demo 的格式

每个 demo 的 README.md 都按统一格式：

1. **本章新概念**：相对上一个 demo 的增量（一两句话）
2. **核心代码差异**：与 demo1 比，主机代码 / shader 改了哪些行
3. **预期输出**：在 Adreno 644 上跑出来的实际样例（含数字）
4. **踩坑**：当前 demo 的 Turnip 特有坑
5. **下一步**：指向下一个 demo

`CLAUDE.md` 记录跨 demo 的公共坑（最经典的就是 Turnip 上
`vkUnmapMemory` 后 host 读会 SIGSEGV），以及"如何新增一个 demo"
的完整流程——是给维护者看的开发文档。