Document current GPU scheduling and Metal behavior

This commit is contained in:
rponeawa
2026-11-02 11:41:59 +08:00
Unverified
parent 7f2c4c15f7
commit d6bd3ddc9a
4 changed files with 91 additions and 297 deletions
+28 -26
View File
@@ -1,37 +1,39 @@
# AdrenoMetal
Start with the [adaptation procedure](/porting/gpu) for board inputs, source changes, build integration and verification order.
AdrenoMetal publishes a Metal device through `MTLAddDevice`. It translates AIR through metal2vulkan, compiles SPIR-V with Turnip, and submits work to [Adreno740](/drivers/adreno740). Firmware, power votes and display integration come from the board.
AdrenoMetal provides the Metal frontend through metal2vulkan and Turnip. It
publishes a device through `MTLAddDevice`, translates AIR, and submits work to
the kernel GPU interface.
## Rendering and interfaces
| Field | Value |
| Area | Behavior |
| --- | --- |
| Repository | [UniXNU/AdrenoMetal](https://github.com/UniXNU/AdrenoMetal) |
| Implementation | A740/SM8550 graphics stack and the selected OS ABI |
| Dependencies | Adreno740, Turnip, metal2vulkan, IOGPUFamily and IOSurface interfaces |
| Board inputs | Firmware, power policy, memory layout, display integration |
| Verified device | sheng |
| Runtime plugin | `NativeAdrenoMetal` |
| Poster MSAA | Poster processes use one sample for textures, pipelines and render passes. Resolve targets receive the rendered output; load and store-and-resolve preserve the source. Other processes retain their requested sample counts. `NATIVE_METAL_SINGLE_SAMPLE=0/1` overrides this policy. |
| Heap resources | Buffer and texture `makeAliasable` release their heap ranges. |
| Texture channels | Texture descriptors and views preserve all four swizzles, including explicit zero and one. |
| Copies and raster state | Blits cover the requested mip and slice ranges. Viewport and scissor setters forward every entry, up to 16. |
| Compressed input | A zero-length no-copy compressed texture infers its DroidVM layout size and retains the owner's deallocator through use. |
| Functions | Function constant dictionaries expose names, indices and types. Function and compute-pipeline completion selectors report results. `specializedName` is the exported name; source lookup retains the original definition. |
| Constant tables | Dynamically indexed constant tables larger than 4 KiB use shared constant storage. Constant pointer casts and GEP expressions retain their offsets. |
| Memory accounting | Device allocation totals include pooled, dedicated and imported backing. Texture sizes come from their backing allocation. The recommended working set is RAM / 4, capped at 2 GiB. |
| Queue capacity | `newCommandQueueWithMaxCommandBufferCount:` uses the runtime's outstanding-buffer limit. Uncommitted destruction releases a slot; completion releases it after handlers return. |
sheng runs the GPU-composited desktop. Exported pipeline caches are reused across
boots. The render server primes every Metal library of the OS image while the
desktop is idle: the payload carries the list (`NativeAdrenoMetal.primelist`) and
a copy of the cryptex QuartzCore library, which the render server's sandbox
cannot reach. The idle desktop submits about 6 command buffers per 250 ms at
120 Hz, so priming waits only above 8. The PR log row shows its progress; all
162 libraries are primed on sheng. With the list present the render server does
not scan directories, and each library is read only while the display is quiet.
The lists, the pipeline pack and the resume rules are in [Warm the shader caches](/porting/gpu#shader-warmup).
A render pass that fails encoding returns an encoder and reports a command-buffer error. This supports callers that cache encoder methods.
A render pass that cannot be encoded still returns an encoder, and its command
buffer is refused: RenderBox caches encoder methods and cannot take nil. The first problem of each process is written to the driver's
per-process text line from the thread that hit it.
## Cache and priority
Clients with the same UID use `Library/Caches/org.unixnu.metal` under their account home when writable. Sandbox restrictions select a private cache. `NATIVE_METAL_SHARED_CACHE_DIR` selects another shared root; an empty value disables sharing. The cache covers Apple frontend output, runtime artifacts and Turnip IR3. Concurrent pack imports use distinct temporary files. Pipeline journals are per process.
Logical Metal queues share one Vulkan queue and kernel queue per process. The frontend forwards the most urgent **current** request among live queues. Lowering or destroying a queue removes its boost. Getters report each queue's own request; setters report backend acceptance. The kernel chooses foreground or background priority from the task's GPU role. Priority policy does not use process names.
## Build and checks
From the resolved sheng iPadOS 27 tree:
```sh
python3 scripts/build-turnip-darwin.py --target ios
python3 scripts/build-adreno-metal-plugin.py
python3 scripts/build-turnip-darwin.py --target ios27
python3 scripts/build-adreno-metal-plugin.py --target ios27
python3 scripts/check-native-metal-frontend-host.py
```
See [Adreno740](/drivers/adreno740) for the runtime path, staging commands, and checks.
The normal build applies the recorded translator and Turnip patches and enables Mesa's disk shader cache. Host checks cover rendered pixels, resolves, resource aliasing, swizzles, copies, callbacks, queue limits and priority aggregation. Hardware qualification covers frame pacing and preemption under concurrent clients.
See the [GPU adaptation procedure](/porting/gpu) for staging and board inputs.
+17 -123
View File
@@ -1,142 +1,36 @@
# Adreno740
Start with the [adaptation procedure](/porting/gpu) for board inputs, source changes, build integration and verification order.
Adreno740 implements the A740 kernel GPU interface used by SM8550. It manages command submission, memory, fences, and GPU initialization. The SoC profile supplies shared GPU, GMU, and SMMU operations. Each board supplies signed firmware, power policy, reserved-memory adjustments, and display integration.
The recorded hardware target is sheng. Its stack uses 4 KiB SMMU translation, GMU firmware, a CP ring, fences, and GPU compositing into scanout.
Adreno740 implements the A740 kernel GPU interface on SM8550. It owns GPU memory mappings, command submission, fences and CP/GMU initialization. The board supplies firmware, power votes and display integration. See the [GPU adaptation procedure](/porting/gpu).
## Runtime path
```mermaid
flowchart LR
A[iPadOS app] --> B[QuartzCore and RenderBox]
B --> C[AdrenoMetal plugin]
C --> D[metal2vulkan]
D --> E[Turnip]
E --> F[NIR and IR3]
F --> G[Darwin KMD]
G --> H[Adreno740]
H --> I[GMU, CP, SMMU and ring]
I --> J[Adreno 740]
J --> K[GPU composite to scanout]
K --> L[GopFramebuffer]
```
Metal → AdrenoMetal → metal2vulkan → Turnip → Darwin KMD → Adreno740 → A740.
1. AdrenoMetal publishes a Metal device through the system `MTLAddDevice` path. The published mode returns the device to backboardd, and listed processes receive their own device. It owns the Metal objects, encoders, IOSurfaces, events, fences and pipeline archives.
2. metal2vulkan translates AIR to SPIR-V and supplies pipeline descriptors, binding plans and function constants.
3. Turnip compiles SPIR-V through NIR to A740 IR3. Its Darwin KMD talks to the Adreno740 user client.
4. Adreno740 owns BOs, GPU addresses, the submission ring, fences and SMMU contexts. The GMU brings the GPU out of reset and applies power votes. The CP executes the IBs.
5. The plugin composites the finished frame into scanout pages. GopFramebuffer offers and retires the swap.
Each client has an address space and queue range. The GPU uses 4 KiB SMMU pages. Owned buffers use system memory; imported pages retain their owners. Allocation capacity follows available memory. Mapping handles are indexed, and unmap invalidates the affected translations.
The runtime compiler chain is Metal, AIR, SPIR-V, NIR, IR3. AirNir is an offline direct AIR to NIR to IR3 compiler.
## Scheduling
## Publish to the render server
`scripts/add-gpu-plugin-data.py` stages the plugin into a copy of the packed Data seed.
| Option | Effect |
| Requested priority | Ring in mode 2 |
| --- | --- |
| `--publish` | Writes `NativeAdrenoMetal.publish`. backboardd returns the native device to the original discovery, and CARenderServer composites the system UI through it. |
| `--clients NAME,...` | Writes `NativeAdrenoMetal.clients`. Each listed process gets its own device and driver connection. Up to two also get a 256 MiB GPU window and their own shader cache. `*` lists every process. |
| High (0), normal-high (4), real-time (5) | 0 |
| Normal (1), low (2), background (3), unspecified | 1 |
The published device turns off backboardd's deep and compressed framebuffers. Patch `zzw-native-adreno-sandbox-grant` lets the accelerator service name the render server in `NativeSandboxGrantProcess`, so its user-client open passes the sandbox check.
The task's GPU role selects its foreground or background request. Ring 0 takes precedence; ring 1 gets service when ring 0 is idle or its oldest job has waited 250 ms. An aging grant gives ring 1 a 2 ms service interval, preventing immediate switch oscillation. Switch completion immediately reevaluates queued high-priority work. Scanout observes the completed prefix across both rings. A queue stays on its existing ring until its outstanding prefix completes, preserving FIFO across priority changes. IB handles identify command storage and do not infer resource dependencies. Turnip's client queues share one kernel FIFO; unresolved syncs wait for producer submission.
Adreno740 serves one user-client core per connection. The render server gets a 1 GiB window at `0x20000000`, and up to two listed clients get 256 MiB each with their own queue range and teardown.
Each ring tracks its queued context and page table. The CP records the executed table after `CP_SMMU_TABLE_UPDATE`, and preemption restores that snapshot. Context switching saves GMEM, runs the performance-counter SRAM postamble and holds the GMU keepalive vote until the incoming WPTR is restored. Read pointers come from each ring's own shadow. Active jobs retain their ring identity when the fence-history table wraps.
## Components
sheng defaults to `sheng-gpu-preempt=2`. Mode 1 sends only low/background requests to ring 1; mode 0 uses one ring. CPU-only page-table switching also uses ring 0. The switch watchdog is 1 s. A failed switch disables further preemption and recovery replays pending work on ring 0; diagnostics retain the failure.
| Component | Role |
| --- | --- |
| `drivers/AdrenoMetal` | Metal frontend, metal2vulkan, command encoding, IOSurface and scanout client |
| `drivers/Adreno740` | GPU service, GMU/CP startup, user client, BO, VM, ring, submit and fence |
| `drivers/GopFramebuffer` | Swap offer, validation, retirement and scanout hand-off |
| `kits/AdrenoFirmware` | GMU HFI, startup, power votes and SQE firmware data |
| `kits/AdrenoPM4` | A740 PM4 state, constants, VPC and rasterizer packets |
| `kits/ArmSmmu4K` | Native 4 KiB tables, context, streams, live mappings and TLB maintenance |
| `kits/AirNir` | Offline AIR to NIR to IR3 compiler |
## Build and verification
## State
| Step | Result |
| --- | --- |
| GMU cold start and HFI | works |
| GPU context and CP commands | works |
| Native 4 KiB SMMU context | active |
| Metal device discovery | works |
| GPU frame copy into scanout | works, pixel-identical |
| Render server compositing | works |
| Per-process Metal devices | works |
| GPU-composited desktop | works |
The GPU path covers discovery, command encoding, pipeline archives, IOSurface imports, fences, compositing and scanout. The render server and listed clients use the native device.
## Memory and TLB
| Item | Behavior |
| --- | --- |
| Objects per client | Limited by memory, found through a handle index |
| Owned BOs | System memory, as Metal resources: pageable memory with no kernel mapping, wired by `prepare()`. The VM zero-fills the pages and sets the write-combined attribute in one batch, and restores it on free. Client views map the BO's own descriptor. No fixed pool. Mapped without the alias check against existing ranges |
| Imported memory | Mapped without that check when every mapped import shares its cache class and none of its pages is in a BO of this driver (a page bitmap over DRAM); otherwise fully checked |
| Unmap | Up to 512 pages invalidated one by one, larger unmaps by ASID |
| Submission | No TLB invalidation; a stalled fence still invalidates |
| Boot log rows | `[vm map]`, `[vm unmap]`, `[vm kinds]`, `[bo memory]` |
## Shader compilation
The driver compiles the original UI shaders on the device:
1. `default.metallib` carries AIR plus Apple GPU machine code. The AIR feeds the translation path.
2. metal2vulkan translates AIR to SPIR-V, then Turnip compiles IR3 at pipeline creation.
3. A cold boot compiles every UI variant it reaches. int-148: 77 pipelines, about 43 s, cache hit 0. int-150: 103 Metal pipelines, 40.1 s total, 1.40 s max; 94 Vulkan pipelines, 23.3 s.
4. Patch `0004` specializes the QuartzCore uber shaders and folds constant loads before inlining. Patch `0005` keeps recent module decodes and device-profile fingerprints. The pipeline journal records each render pipeline creation.
Implemented mitigations:
| Mitigation | Effect |
| --- | --- |
| NDEBUG release build | Removes per-pass Mesa assertions and NIR validation. |
| metal2vulkan patch `0004` | Specializes and prunes QuartzCore uber shaders before Vulkan compilation. |
| metal2vulkan patch `0005` | Keeps recent module decodes and device-profile fingerprints. |
| Priming cache | Caches runtime startup entry-point work. |
| `m2vpack` export and import | Reuses earlier compiled pipeline caches; the export is incremental. |
| Turnip builtin pack | Embeds clear, blit and empty shader variants. |
| Pipeline journal | Records per-pipeline CPU and system time, page faults and context switches. |
The cache chain covers runtime startup and the UI variants an earlier boot exported. A new UI variant compiles once, then enters the exported cache.
## Build
From the resolved sheng iPadOS 27 tree, with `UNIXNU_XNU_ARCH=arm64e` and `UNIXNU_IOS_VERSION=27.0`:
```sh
python3 scripts/build-turnip-darwin.py --target ios
python3 scripts/build-adreno-metal-plugin.py
python3 scripts/add-gpu-plugin-data.py --publish --clients <name,...> <seed>.dbr <output>.dbr
python3 scripts/build-arm-driver.py Adreno740
python3 scripts/build-adreno740-kits.py
python3 scripts/check-native-adreno-scheduling.py
```
The staging script output is the Data seed for `unixnu build payload --data-ramdisk`.
The host scheduling check runs the real ring, preemption and submit code over software register peers with address and undefined-behavior sanitizers. It checks packets, GMEM and keepalive sequencing, timeout handling, page-table snapshots, priority routing, FIFO and fence-history rollover. Hardware qualification requires concurrent clients, repeated ring switches, correct pixels and frame-pacing measurements.
Host checks:
```sh
python3 scripts/check-native-metal-frontend-host.py
python3 scripts/check-turnip-darwin-host.py
python3 scripts/check-smmu4k-live.py
python3 scripts/check-turnip-pipeline-cache-host.py
python3 scripts/check-priming-cache-host.py --output build/priming-cache/run
python3 scripts/probe-turnip-internal-compiler-host.py --qualification <old> --output <new>
```
The device repository adds the original-input checks:
```sh
python3 scripts/build-adreno-compiler-host.py --probe
python3 scripts/build-turnip-ios-compiler-peer.py
python3 scripts/check-turnip-ios-compiler-cache.py
python3 scripts/check-quartzcore-turnip-cache-host.py
```
## Related
- [Xiaomi Pad 6S Pro (sheng)](/devices/sheng)
- [XNU drivers](/drivers/xnu-drivers)
- [Four-kilobyte pages](/xnu/four-k-page-tables)
See [AdrenoMetal](/drivers/adreno-metal) for Metal interfaces, caches and plugin staging.
+28 -24
View File
@@ -1,35 +1,39 @@
# AdrenoMetal
先按[适配流程](/zh/porting/gpu)准备板级输入、修改源码、接入构建并逐步验证。
AdrenoMetal 通过 `MTLAddDevice` 发布 Metal 设备。metal2vulkan 将 AIR 翻译为 SPIR-V,Turnip 完成编译,并向 [Adreno740](/zh/drivers/adreno740) 提交任务。固件、电源投票和显示集成由设备仓库提供。
AdrenoMetal 通过 metal2vulkan 和 Turnip 提供 Metal 前端。它通过 `MTLAddDevice`
发布设备,翻译 AIR,并向内核 GPU 接口提交任务。
## 渲染和接口
| 字段 | 值 |
| 项目 | 当前行为 |
| --- | --- |
| 仓库 | [UniXNU/AdrenoMetal](https://github.com/UniXNU/AdrenoMetal) |
| 实现 | A740/SM8550 图形栈和所选 OS ABI |
| 依赖 | Adreno740、Turnip、metal2vulkan、IOGPUFamily 和 IOSurface 接口 |
| 板级输入 | 固件、电源策略、内存布局、显示集成 |
| 已验证设备 | sheng |
| 运行时插件 | `NativeAdrenoMetal` |
| Poster MSAA | Poster 进程的纹理、管线和渲染通道统一使用单采样。resolve 目标接收渲染结果,load 和 store-and-resolve 保留源内容。其他进程保留请求的采样数。`NATIVE_METAL_SINGLE_SAMPLE=0/1` 可覆盖此策略。 |
| Heap 资源 | buffer 和 texture 的 `makeAliasable` 归还 heap 区间。 |
| 纹理通道 | 纹理描述符和 view 保留全部四个 swizzle,包括显式零和一。 |
| 复制和光栅状态 | blit 覆盖指定 mip 和 slice 范围。viewport、scissor 传递完整数组,最多 16 项。 |
| 压缩纹理输入 | 长度为零的 no-copy 压缩纹理按 DroidVM 布局推导大小,使用结束后调用所有者的 deallocator。 |
| 函数 | 函数常量字典提供名称、索引和类型。函数及计算管线的完成回调返回结果。`specializedName` 用作导出名称,源码查找保留原函数名。 |
| 常量表 | 超过 4 KiB 的动态索引常量表使用共享常量存储。常量指针转换和 GEP 表达式保留偏移。 |
| 内存统计 | 设备用量统计池、独立和导入分配。纹理大小来自实际 backing allocation。建议工作集为 RAM / 4,上限 2 GiB。 |
| 队列容量 | `newCommandQueueWithMaxCommandBufferCount:` 使用 runtime 的未完成缓冲数量限制。未提交缓冲销毁时释放名额,已提交缓冲在完成回调返回后释放名额。 |
sheng 已运行 GPU 合成桌面。导出的 pipeline cache 可在后续启动复用。桌面空闲时,
render server 会预编译系统镜像中的全部 Metal 库:payload 带有库列表
(`NativeAdrenoMetal.primelist`),以及一份 cryptex 中 QuartzCore 库的副本,因为
render server 的沙盒访问不到 cryptex 路径。120 Hz 下空闲桌面每 250 ms 提交约
6 个命令缓冲区,所以只有超过 8 个时预编译才会等待。日志 PR 行显示进度;sheng 上
162 个库已全部预编译。有列表时 render server 不扫描目录,并且只在显示空闲时读取
每个库。
列表、pipeline 包和续编译规则见[预热着色器缓存](/zh/porting/gpu#shader-warmup)。
渲染通道编码失败时仍返回 encoder,通过 command buffer 报错,支持缓存 encoder 方法的调用方。
无法编码的 render pass 仍返回 encoder,并拒绝其命令缓冲区:RenderBox 会缓存
encoder 的方法,不能接受 nil。每个进程的第一个问题由出错
的线程写入驱动的进程文本行。
## 缓存和优先级
相同 UID 的客户端在可写时共用账户 home 下的 `Library/Caches/org.unixnu.metal`。沙箱限制写入时使用私有缓存。`NATIVE_METAL_SHARED_CACHE_DIR` 可指定共享目录,空值关闭共享。缓存覆盖 Apple 前端结果、runtime 产物和 Turnip IR3。并发导入使用独立临时文件,管线日志按进程分开。
同一进程的 Metal 逻辑队列共用一个 Vulkan 队列和内核队列。前端汇总存活队列的当前请求,采用其中最高的优先级;队列降级或销毁后撤回提升。getter 返回各队列自身的请求,setter 返回后端是否接受。内核根据任务的 GPU role 选择前台或后台优先级,策略不使用进程名。
## 构建和检查
在解析后的 sheng iPadOS 27 构建树中执行:
```sh
python3 scripts/build-turnip-darwin.py --target ios
python3 scripts/build-adreno-metal-plugin.py
python3 scripts/build-turnip-darwin.py --target ios27
python3 scripts/build-adreno-metal-plugin.py --target ios27
python3 scripts/check-native-metal-frontend-host.py
```
运行时流程、发布命令和检查见 [Adreno740](/zh/drivers/adreno740)。
正常构建应用记录在仓库中的翻译器、Turnip 补丁,并开启 Mesa 磁盘 shader cache。主机检查覆盖渲染像素、resolve、资源回收、swizzle、复制、回调、队列容量及优先级汇总。上机验证项目是并发客户端下的帧间隔和抢占行为。
设备输入和打包方式见 [GPU 适配流程](/zh/porting/gpu)。
+18 -124
View File
@@ -1,142 +1,36 @@
# Adreno740
先按[适配流程](/zh/porting/gpu)准备板级输入、修改源码、接入构建并逐步验证。
Adreno740 实现 SM8550 上的 A740 内核 GPU 接口,负责内存映射、命令提交、fence 和 CP/GMU 初始化。设备仓库提供固件、电源投票和显示集成。适配入口见 [GPU 适配流程](/zh/porting/gpu)。
Adreno740 实现 SM8550 使用的 A740 内核 GPU 接口,管理命令提交、内存、fence 和 GPU 初始化。SoC 配置提供共享 GPU、GMU 和 SMMU 操作。各设备提供签名固件、电源策略、保留内存调整和显示集成。
## 运行路径
已有硬件记录的设备为 sheng。其图形栈使用 4 KiB SMMU 翻译、GMU 固件、CP ring、fence 和 GPU 到 scanout 的合成。
Metal → AdrenoMetal → metal2vulkan → Turnip → Darwin KMD → Adreno740 → A740。
## 运行时链路
每个客户端拥有独立地址空间和队列编号范围。GPU 使用 4 KiB SMMU 页。自有 buffer 使用系统内存,导入页保留所有者。分配容量随可用内存变化。映射句柄通过索引查找,解除映射时失效对应转换。
```mermaid
flowchart LR
A[iPadOS 应用] --> B[QuartzCore 和 RenderBox]
B --> C[AdrenoMetal 插件]
C --> D[metal2vulkan]
D --> E[Turnip]
E --> F[NIR 和 IR3]
F --> G[Darwin KMD]
G --> H[Adreno740]
H --> I[GMU、CP、SMMU 和 ring]
I --> J[Adreno 740]
J --> K[GPU 合成到 scanout]
K --> L[GopFramebuffer]
```
## 调度
1. AdrenoMetal 通过系统 `MTLAddDevice` 发布 Metal 设备。发布模式把设备交回 backboardd,白名单进程获得各自的设备。它管理 Metal 对象、编码器、IOSurface、event、fence 和 pipeline archive。
2. metal2vulkan 把 AIR 翻译成 SPIR-V,并给出 pipeline 描述、binding 计划和 function constant。
3. Turnip 把 SPIR-V 经过 NIR 编译成 A740 IR3。Darwin KMD 通过 Adreno740 user client 访问内核。
4. Adreno740 管理 BO、GPU 地址、提交 ring、fence 和 SMMU context。GMU 让 GPU 退出 reset 并提交功耗票,CP 执行 IB。
5. 插件把完成帧合成到 scanout 页,GopFramebuffer 提供并回收 swap。
运行时编译链路是 Metal、AIR、SPIR-V、NIR、IR3。AirNir 是离线的 AIR 到 NIR 到 IR3 编译器。
## 发布到 render server
`scripts/add-gpu-plugin-data.py` 把插件写入打包 Data seed 的副本。
| 选项 | 作用 |
| 请求优先级 | 模式 2 使用的环 |
| --- | --- |
| `--publish` | 写入 `NativeAdrenoMetal.publish`。backboardd 把原生设备交回原有发现流程,CARenderServer 通过它合成系统界面。 |
| `--clients NAME,...` | 写入 `NativeAdrenoMetal.clients`。每个列入的进程获得自己的设备和驱动连接;其中最多两个还获得 256 MiB GPU 窗口和自己的 shader cache。`*` 表示所有进程。 |
| High(0)、normal-high(4)、real-time(5) | ring 0 |
| Normal(1)、low(2)、background(3)、未指定 | ring 1 |
发布模式关闭 backboardd 的 deep framebuffer 和压缩 framebuffer。补丁 `zzw-native-adreno-sandbox-grant` 让加速器服务在 `NativeSandboxGrantProcess` 中指定 render server,使其 user client 打开通过沙箱检查。
任务的 GPU role 决定采用前台还是后台请求。ring 0 优先;ring 0 空闲,或 ring 1 最早的任务等待超过 250 ms 时,调度 ring 1。超时等待获得的执行时间片为 2 ms,避免立即来回切环。切换完成后重新检查排队中的高优先级任务。显示端使用两个环共同完成的连续 fence 范围。队列在已有任务完成前保持原来的环,改优先级时仍按提交顺序执行。IB 句柄只标识命令存储,不用于推断资源依赖。Turnip 客户端的队列共用一个内核 FIFO,未解析的同步等待生产者提交。
Adreno740 为每个连接提供一个 user-client core。render server 获得 `0x20000000` 处 1 GiB 窗口,最多两个列入的客户端各获得 256 MiB 及自己的队列范围和回收路径。
每个环独立记录已排队的上下文和页表。CP 在 `CP_SMMU_TABLE_UPDATE` 后记录实际执行的页表,抢占恢复该快照。切环保存 GMEM,执行性能计数器 SRAM postamble,并保持 GMU keepalive,直到目标环 WPTR 恢复。读指针使用各环自己的 shadow。fence 历史表绕回后,未完成任务仍保留正确的环归属。
## 组件
sheng 默认使用 `sheng-gpu-preempt=2`。模式 1 仅将 low/background 请求送往 ring 1,模式 0 使用单环。由 CPU 切换页表时也仅使用 ring 0。切环超时为 1 秒。切换失败后停止抢占,恢复流程在 ring 0 重放待执行任务,诊断记录保留失败信息。
| 组件 | 作用 |
| --- | --- |
| `drivers/AdrenoMetal` | Metal 前端、metal2vulkan、命令编码、IOSurface 和 scanout client |
| `drivers/Adreno740` | GPU 服务、GMU/CP 启动、user client、BO、VM、ring、提交和 fence |
| `drivers/GopFramebuffer` | swap 提供、校验、回收和 scanout hand-off |
| `kits/AdrenoFirmware` | GMU HFI、启动、功耗票和 SQE 固件数据 |
| `kits/AdrenoPM4` | A740 PM4 状态、常量、VPC 和 rasterizer 包 |
| `kits/ArmSmmu4K` | 原生 4 KiB 表、context、stream、live mapping 和 TLB 维护 |
| `kits/AirNir` | 离线 AIR 到 NIR 到 IR3 编译器 |
## 构建和验证
## 状态
| 步骤 | 结果 |
| --- | --- |
| GMU 冷启动和 HFI | 工作 |
| GPU context 和 CP 命令 | 工作 |
| 原生 4 KiB SMMU context | active |
| Metal 设备发现 | 工作 |
| GPU 帧复制到 scanout | 工作,像素一致 |
| render server 合成 | 工作 |
| 每进程 Metal 设备 | 工作 |
| GPU 合成桌面 | 工作 |
GPU 路径覆盖发现、命令编码、pipeline archive、IOSurface 导入、fence、合成和 scanout。render server 和列入的客户端使用原生设备。
## 内存与 TLB
| 项目 | 行为 |
| --- | --- |
| 每客户端对象数 | 只受内存限制,通过 handle 索引查找 |
| 自有 BO | 与 Metal 资源一样来自系统内存:没有内核映射的可分页内存,由 `prepare()` 锁定。VM 清零页面并一次批量设置 write-combined 属性,释放时恢复。客户端视图映射 BO 自己的描述符。没有固定池。映射时不做与已有区间的别名检查 |
| 导入内存 | 已映射的导入都属同一缓存类别,且其页都不在本驱动的 BO 中(覆盖 DRAM 的页位图)时,同样不做该检查;否则完整检查 |
| 解除映射 | 不超过 512 页逐页失效,更多时按 ASID 失效 |
| 提交 | 不做 TLB 失效;fence 卡住时仍会失效 |
| 启动日志行 | `[vm map]`、`[vm unmap]`、`[vm kinds]`、`[bo memory]` |
## 着色器编译
驱动在设备上编译原始 UI shader:
1. `default.metallib` 带有 AIR 和 Apple GPU 机器码,AIR 进入翻译路径。
2. metal2vulkan 把 AIR 翻译成 SPIR-V,Turnip 在 pipeline 创建时编译 IR3。
3. 冷启动会编译它遇到的每个 UI 变体。int-148:77 个 pipeline,约 43 s,cache hit 0。int-150:103 个 Metal pipeline,共 40.1 s,最大 1.40 s;94 个 Vulkan pipeline,共 23.3 s。
4. 补丁 `0004` 在 inlining 前特化 QuartzCore uber shader 并折叠常量加载。补丁 `0005` 保留最近的 module decode 和 device-profile fingerprint。pipeline journal 记录每次 render pipeline 创建。
已实现的缓解:
| 缓解 | 效果 |
| --- | --- |
| NDEBUG release 构建 | 去掉每 pass 后的 Mesa assertion 和 NIR 校验。 |
| metal2vulkan 补丁 `0004` | 在 Vulkan 编译前特化和裁剪 QuartzCore uber shader。 |
| metal2vulkan 补丁 `0005` | 保留最近的 module decode 和 device-profile fingerprint。 |
| priming cache | 缓存运行时启动 entry point 工作。 |
| `m2vpack` 导出和导入 | 复用之前编译的 pipeline cache;导出是增量的。 |
| Turnip builtin pack | 内嵌 clear、blit 和 empty shader 变体。 |
| pipeline journal | 记录每个 pipeline 的 CPU 时间、系统时间、page fault 和上下文切换。 |
cache 链路覆盖运行时启动和之前启动导出过的 UI 变体。新的 UI 变体编译一次后进入导出 cache。
## 构建
在解析后的 sheng iPadOS 27 构建树中设置 `UNIXNU_XNU_ARCH=arm64e`、`UNIXNU_IOS_VERSION=27.0` 后执行:
```sh
python3 scripts/build-turnip-darwin.py --target ios
python3 scripts/build-adreno-metal-plugin.py
python3 scripts/add-gpu-plugin-data.py --publish --clients <name,...> <seed>.dbr <output>.dbr
python3 scripts/build-arm-driver.py Adreno740
python3 scripts/build-adreno740-kits.py
python3 scripts/check-native-adreno-scheduling.py
```
staging 脚本的输出是 `unixnu build payload --data-ramdisk` 使用的 Data seed。
主机调度检查使用软件寄存器模型运行实际 ring、preemption 和 submit 代码,并开启地址及未定义行为检查。覆盖命令包、GMEM、keepalive 顺序、超时、页表快照、优先级分环、FIFO 和 fence 历史表绕回。上机验证项目包括并发客户端、反复切环、像素正确性和帧间隔。
主机检查:
```sh
python3 scripts/check-native-metal-frontend-host.py
python3 scripts/check-turnip-darwin-host.py
python3 scripts/check-smmu4k-live.py
python3 scripts/check-turnip-pipeline-cache-host.py
python3 scripts/check-priming-cache-host.py --output build/priming-cache/run
python3 scripts/probe-turnip-internal-compiler-host.py --qualification <old> --output <new>
```
设备仓库增加原始输入检查:
```sh
python3 scripts/build-adreno-compiler-host.py --probe
python3 scripts/build-turnip-ios-compiler-peer.py
python3 scripts/check-turnip-ios-compiler-cache.py
python3 scripts/check-quartzcore-turnip-cache-host.py
```
## 相关
- [小米平板 6S Pro(sheng)](/zh/devices/sheng)
- [XNU 驱动](/zh/drivers/xnu-drivers)
- [4 KiB 页表](/zh/xnu/four-k-page-tables)
Metal 接口、缓存和插件打包见 [AdrenoMetal](/zh/drivers/adreno-metal)。