📚 课程目录第4章开发环境搭建

4、开发环境搭建：Android NDK、OpenGL ES、Vulkan、Mali驱动与调试工具安装配置

ARM Mali GPU 的移动端开发与传统的桌面图形开发有显著差异：目标平台是 Android 系统，底层通过 JNI 调用原生图形 API，且不同厂商（如华为麒麟、三星 Exynos、联发科天玑）对 Mali GPU 的驱动实现存在细微差别。本章将系统梳理从零搭建一套可用的 Mali GPU 开发环境所需的全部组件，包括 Android NDK、OpenGL ES 与 Vulkan 的 API 层配置、Mali 驱动与用户态库的匹配关系，以及性能调试工具链的安装与验证方法。环境搭建的成败直接决定后续渲染调试的效率，因此本章内容以“可复现、可验证”为第一原则。

上图展示了 Mali GPU 开发环境的整体架构：主机侧负责代码编译与打包，目标设备侧提供 GPU 硬件与驱动，中间通过 OpenGL ES 或 Vulkan API 进行交互，调试工具则通过 ADB 或 USB 连接进行性能数据采集。理解这条链路中各组件之间的依赖关系，是正确配置环境的前提。

4.1 核心原理：Android 图形栈与 Mali 驱动分层

Android 的图形系统采用分层架构，从应用层到硬件层共涉及五个关键层级。对于 Mali GPU 开发而言，理解每一层的职责和接口边界至关重要。

应用框架层（Java/Kotlin）：通过 SurfaceView 或 TextureView 创建渲染表面，调用 EGL 或 Vulkan 的 Java 绑定接口。
Native 层（C/C++）：通过 JNI 调用 libEGL.so、libGLESv3.so 或 libvulkan.so，这些库由 Android 系统提供，但底层实现由 GPU 驱动厂商（Arm）完成。
HAL 层（Hardware Abstraction Layer）：Android 的 gralloc 和 hwcomposer 模块负责内存分配与合成，Mali 驱动通过 libgralloc_mali 实现。
内核驱动层：Mali 的 mali_kbase 内核模块负责 GPU 的电源管理、内存管理（通过 DMA-BUF）和命令队列提交。
用户态驱动层：libmali.so（或 libGLES_mali.so）是 Arm 提供的闭源二进制库，实现了 OpenGL ES 和 Vulkan 的 API 入口，并直接与内核驱动交互。

开发者在搭建环境时，最容易忽略的是用户态驱动与内核驱动的版本匹配问题。如果设备厂商没有正确更新 /vendor/lib64/egl/libGLES_mali.so，即使安装了最新的 NDK，也无法使用 Vulkan 1.3 的新特性。因此，环境搭建的第一步不是安装软件，而是确认目标设备的驱动版本。

经验提醒：在开发前，先通过 adb shell dumpsys SurfaceFlinger | grep GLES 查看当前设备的 OpenGL ES 版本和 Mali 驱动字符串。例如输出 Mali-G78 表示 GPU 型号，r40p0 表示驱动版本。记录这些信息，后续所有工具链的版本选择都以此为依据。

4.2 操作流程：NDK 与 CMake 的安装配置

Android NDK 是编译原生代码的必备工具集。对于 Mali GPU 开发，推荐使用 NDK r25 或更高版本，因为其内置的 LLVM 工具链对 Vulkan 头文件支持更完整。

安装 NDK 与 CMake：通过 Android Studio 的 SDK Manager 安装 NDK（Side-by-side）和 CMake 3.22+。也可以使用命令行工具 sdkmanager 安装。
配置 ABI 与 API Level：在 build.gradle 中设置 ndk { abiFilters 'arm64-v8a' }，并指定 minSdkVersion 24（Android 7.0），以确保支持 Vulkan 1.0 及以上版本。
编写 CMakeLists.txt：需要显式链接 GLESv3 和 EGL，或者 vulkan 库。示例配置如下：

cmake_minimum_required(VERSION 3.22)
project(mali_demo)

add_library(native-lib SHARED native-lib.cpp)

# 链接 OpenGL ES 3.2 和 EGL
target_link_libraries(native-lib
    android
    GLESv3
    EGL
    log)

# 如果使用 Vulkan，则添加：
# find_package(Vulkan REQUIRED)
# target_link_libraries(native-lib Vulkan::Vulkan)

配置完成后，通过 adb install 将 APK 部署到设备。此时可以编写一个简单的初始化代码，调用 eglGetDisplay() 和 eglInitialize() 来验证 EGL 环境是否正常。

4.3 案例拆解：Vulkan 初始化与 Mali 驱动验证

下面通过一个实际案例，演示如何验证 Vulkan 环境是否在 Mali GPU 上正确工作。该案例的目标是创建一个 Vulkan 实例并枚举物理设备，确认 Mali GPU 被正确识别。

背景与约束：开发机为 Ubuntu 22.04，目标设备为搭载 Mali-G710 GPU 的 Android 13 手机。已知该设备厂商提供了 Vulkan 1.3 驱动，但不确定是否支持 VK_KHR_portability_enumeration 扩展。

初始现象：直接运行 Vulkan 应用时，vkCreateInstance 返回 VK_ERROR_INCOMPATIBLE_DRIVER，导致应用崩溃。

分析过程：通过 adb logcat 查看日志，发现驱动报告缺少 VK_KHR_portability_enumeration 扩展。该扩展在 macOS 上必需，但在 Android 上并非强制。问题根源在于代码中无条件启用了该扩展。

操作步骤：修改代码，在启用扩展前先查询设备支持的扩展列表。关键代码如下：

uint32_t extCount = 0;
vkEnumerateInstanceExtensionProperties(nullptr, &extCount, nullptr);
std::vector<VkExtensionProperties> exts(extCount);
vkEnumerateInstanceExtensionProperties(nullptr, &extCount, exts.data());

bool portabilitySupported = false;
for (const auto& ext : exts) {
    if (strcmp(ext.extensionName, "VK_KHR_portability_enumeration") == 0) {
        portabilitySupported = true;
        break;
    }
}

VkInstanceCreateInfo createInfo{};
createInfo.sType = VK_STRUCTURE_TYPE_INSTANCE_CREATE_INFO;
if (portabilitySupported) {
    createInfo.flags |= VK_INSTANCE_CREATE_ENUMERATE_PORTABILITY_BIT_KHR;
}

结果对比：修改后，vkCreateInstance 成功，vkEnumeratePhysicalDevices 返回 Mali-G710 设备，且支持 Vulkan 1.3 的 VK_KHR_dynamic_rendering 特性。

复盘经验：在 Mali 平台上，Vulkan 扩展的支持情况因驱动版本而异。建议在应用启动时动态查询扩展，而不是硬编码。同时，使用 VK_EXT_debug_utils 可以捕获驱动层的警告信息，这对排查初始化问题非常有帮助。

风险提示：不要假设所有 Mali 设备都支持 Vulkan 1.3。部分中低端设备（如 Mali-G52）仅支持 Vulkan 1.1。在 build.gradle 中设置 vulkanVersion 时，应使用 1.1.0 作为最低版本，并在运行时检查实际版本。

4.4 常见误区与总结复盘

在环境搭建过程中，开发者常遇到以下几类问题，这里逐一分析并给出解决方案。

误区	现象	根因	解决方案
NDK 版本过旧	编译时找不到 `vulkan.h`	NDK r23 之前不包含 Vulkan 头文件	升级到 NDK r25+，或手动下载 Vulkan-Headers
ABI 不匹配	安装 APK 后闪退，`dlopen` 失败	只编译了 `armeabi-v7a`，但设备是 64 位	在 `abiFilters` 中添加 `arm64-v8a`
驱动版本过旧	Vulkan 初始化失败，`VK_ERROR_INITIALIZATION_FAILED`	系统镜像中的 `libmali.so` 不支持所需扩展	刷入厂商提供的最新固件，或使用 `adb shell setprop debug.hwui.renderer opengl` 降级测试
调试工具无法连接	Streamline 显示“No devices found”	未开启 USB 调试的“安全设置”权限	在开发者选项中启用“USB 调试（安全设置）”

总结本章内容，环境搭建的核心要点可以归纳为三个“匹配”：NDK 版本与 API Level 匹配、用户态驱动与内核驱动匹配、调试工具与 GPU 架构匹配。建议开发者在项目初期就建立一套环境验证脚本，自动检查这些匹配关系，避免在开发中期才暴露环境问题。

  实战建议：在项目根目录创建 check_env.sh 脚本，内容包含：

  1. 检查 NDK 版本：ndk-build --version

  2. 检查设备 GL 信息：adb shell dumpsys SurfaceFlinger | grep GLES

  3. 检查 Vulkan 支持：adb shell cmd gpu vkjson

  4. 检查 Mali 驱动路径：adb shell ls -l /vendor/lib64/egl/libGLES_mali.so

  每次开始开发前运行该脚本，确保环境一致。

最后需要强调的是，Mali GPU 的调试工具链（如 Arm Streamline 和 Mali Offline Compiler）虽然功能强大，但需要与目标设备的驱动版本严格对应。例如，Streamline 6.3 仅支持 Mali-G78 及之后的 GPU，对于老旧的 Mali-T860 则需要使用 5.6 版本。在安装这些工具时，务必查阅 Arm 官方的版本兼容性矩阵，避免因工具版本过新而无法识别设备。