Skip to content

MACBOX_VIDEO: hardware VideoToolbox for the Device panel's stream - #14

Merged
0xdaniell merged 5 commits into
mainfrom
video-encode
Nov 14, 2026
Merged

0xdaniell merged 5 commits into
mainfrom
video-encode

Conversation

@0xdaniell

@0xdaniell 0xdaniell commented Nov 14, 2026 •

Copy link
Copy Markdown
Owner

What

  • MACBOX_VIDEO=on adds Reims's VideoToolbox (apple-videotoolbox-pci) and M2 scaler (apple-m2scaler-pci) devices to QEMU, so H.264/HEVC encode and decode in the guest run on the host GPU through VA-API.
  • QEMU patch 0014 adds both devices (upstream qemu-reims-vgpu 4895365e5b).
  • macbox video-kexts copies reims-util's x86-64 ports of Apple's paravirtual video drivers into OpenCore (src/guest/bin/opencore-video-kexts.sh).
  • Default: off. Nothing changes unless it is turned on.
  • docs/performance.md gains two sections. The first covers where a Device panel frame's time goes (copy, encode, wire, decode). The second shows that with Coherent on, the Simlock capture's fps throttle, not the GPU, capped the stream at 50-52 fps; paced on a grid it gives 58.6-58.8.

Tested (Tahoe, macOS 26.7.1 25G241, Arrow Lake iGPU, 2026-11-13/14)

  • Encoder: VideoToolbox picks the hardware encoder. ~9 ms per 1206x2622 frame, encoder process ~0% CPU and 10-18 MB.
  • Stream throughput (Simlock gateway stream, the route T3's Device panel uses):
    • GlassBench 58.6-58.8 fps.
    • Safari scroll 51.5 fps.
    • Tap to decoded frame p50 ~61 ms.
  • Running time: the production VM has run with MACBOX_VIDEO's devices since 2026-11-13 evening.

Not verified

  • Hardware and OS coverage: other GPUs, and macOS builds other than 25G241. The kexts are tied to it, which the docs say.
  • Fresh install: macbox video-kexts has not been run end to end on a fresh install. Production's kexts were installed by the same script steps, by hand.
  • Measurement path: the fps figures are measured at the gateway stream, not inside T3's panel client. Measuring there is in progress.

Review fixes (c198f57), tested on macOS 26.7.1 (25G241) against a throwaway FAT disk image

  • An existing entry is set to the required values: a disabled VtWaitPatch.kext entry with MaxKernel 25.99.99 and a wrong ExecutablePath came out enabled, 25.6.0–25.6.99 and correct. The other two were added, and an unrelated entry was left alone.
  • A second run changes nothing; the plist still has 4 entries.
  • Staged then swapped: with a kext too big for the partition, the copy failed with "No space left on device", the script exited 1, config.plist was byte-identical (md5), the old kexts were unchanged, and no staging folders were left.
  • MaxKernel 25.6.99, and the script refuses any build other than 25G241 unless FORCE=1. Runs under macOS's bash 3.2.
  • Not exercised: the rollback when a rename fails part way through the swap (no way to inject that on FAT).

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 14, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-14T13:08:16.526094Z c198f57 New commits
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

The pinned QEMU (bd95509) predates upstream's apple-videotoolbox-pci and
apple-m2scaler-pci, so a macbox build could not attach Reims's hardware
video devices. 0014 is upstream's commit as it is; it goes away when
QEMU_REF moves past it. Built and run on Tahoe since 2026-11-13 19:00Z
(qemu 20261113-190049-r8dea1e59-qaed2b83-video).
MACBOX_VIDEO=on (default off) attaches apple-videotoolbox-pci and
apple-m2scaler-pci at the slots reims-ctl's newer releases use. An x86-64
guest needs reims-util's ports of Apple's drivers and its VtWaitPatch in
OpenCore: reims-util 8a8a852 and later put them in every image; for an
image made earlier, macbox video-kexts adds the same three entries
(src/guest/bin/opencore-video-kexts.sh), keeping config.plist.before-video.

On Tahoe (2026-11-13) the Device panel's 1206x2622 stream went from
VideoToolbox's software encoder (613-620 MB, 73-75% of a core scrolling,
82 ms a frame) to the host GPU's (9-18 MB, ~0%, 8-9 ms).
The per-frame 60 ms was IOSurfaceLock waiting for the simulator's frame
to finish on the GPU, not a readback; the stream keeps up with the
simulator's own rate. Measured on Tahoe, 2026-11-13.
…wap with rollback, 25G241 only

Review of #14: an entry already in config.plist was trusted by name, even disabled or with other
paths or kernel limits; the kexts were replaced and config.plist edited in place, so a full EFI
partition or an interruption could leave missing kexts or half an entry; MaxKernel 25.99.99 allowed
more than the 26.7 the patch is for.
Now each entry is set to the required values, the edited config.plist is checked in /tmp and the new
kexts copied beside the old ones before anything changes, then both are swapped in by renames with
the old ones put back on a failure. MaxKernel is 25.6.99, and the script refuses a build other than
25G241 unless FORCE=1. bash 3.2 compatible (macOS's /bin/bash).

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c198f57d5c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread macbox
Comment on lines +319 to +320
local rev=${1:-8a8a852} src="$MACBOX_HOME/src/reims-util" t
[ -d "$src/.git" ] || git clone -q https://github.com/steelbrain/reims-util "$src"

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Fetch the video kexts into a user-writable directory

For a non-root user whose installation was built with rootful Docker, macbox video-kexts fails before copying any drivers: src/container/build-reims.sh creates $MACBOX_HOME/src inside the build container, and neither cmd_build nor the Dockerfile selects a non-root user, so that directory is normally root-owned and not writable from this host-side git clone. Run the fetch/archive inside the container, as the existing build does, or use a separate user-writable checkout location.

Useful? React with 👍 / 👎.

@0xdaniell
0xdaniell merged commit 8cb9b3f into main Nov 14, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant