Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,11 @@ back from the GPU, 2 to 3 frames a second, so macbox never uses it.
`macbox stream novnc` switches to noVNC over wayvnc (no rate control).
- **Local.** `macbox view local` mounts the invoking user's Wayland socket into the container, and
the window opens on the host's desktop, full screen and 1:1: nothing is captured or encoded.
- **Switching** (`MACBOX_VIEW_SWITCH=on`). The container gets the host's socket whatever the view,
sway runs too, and Reims reads the socket to show on from `run/compositor`
(`REIMS_VGPU_WINDOW_COMPOSITOR_FILE`, Reims 0036). `macbox view` rewrites the file and waits for
`run/compositor.on`: the window closes on one compositor and opens on the other, while the
guest and its display run on. Nothing renders into the place that isn't shown.

The screen's size is `$MACBOX_HOME/run/resolution` (`macbox resolution WxH`); sway's output and
Selkies follow it.
Expand Down
3 changes: 3 additions & 0 deletions docs/setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@ node), makes an SSH key `~/.ssh/macbox_ed25519`, and adds a `Host macbox` block
| `MACBOX_DISK_CACHE` | none | `writeback` panicked macOS's NVMe driver under heavy swap; `unsafe` is faster, but a crash of the host itself can corrupt the VM's disk. Applies at the next `macbox up` |
| `MACBOX_COHERENT` | auto | `auto`: on with an Arrow Lake iGPU. Coherent, zero-copy surfaces, and the switches measured with it: a 3x simulator 50 → 120 fps there ([performance.md](performance.md#coherent-and-the-switches-measured-with-it-on-by-default-on-arrow-lake)); `on` with any GPU, `off` |
| `MACBOX_VIDEO` | off | `on`: Reims's hardware VideoToolbox and M2 scaler devices, so the guest's H.264/HEVC encoding (the Device panel's stream) and decoding run on the host GPU through VA-API instead of VideoToolbox's software encoder. Needs the video kexts in OpenCore first (`macbox video-kexts`); macOS 26.7 (25G241) only. See [performance.md](performance.md#hardware-video-encoding-macbox_video) |
| `MACBOX_VIEW_SWITCH` | off | `on`: `macbox view local\|stream` moves the running VM's window between the host's desktop and the browser stream without a restart (Reims 0036). Takes effect at the next `macbox up`, which must run from a shell in the Wayland session |
| `MACBOX_HOME` | ~/.local/share/macbox | everything macbox keeps |

Then:
Expand Down Expand Up @@ -74,6 +75,8 @@ builds Reims's current master as it is, without macbox's patches.
The screen: open http://127.0.0.1:6081/ in a browser on the host (Selkies). Or, if you sit at the
host and it runs a Wayland desktop, `./macbox view local` opens macOS in a window there, with no
encoding at all. Click into it to give it the keyboard; Ctrl+Alt+Super gives the keyboard back.
`view` restarts the VM; with `MACBOX_VIEW_SWITCH=on` the window moves between the two while macOS
runs (after one `macbox down && macbox up` from a shell on the desktop).

To watch from another machine, forward the port: `ssh -L 6081:127.0.0.1:6081 <host>`, then open
http://127.0.0.1:6081/ there. Or publish it on a tailnet (`tailscale serve --bg --https=8481
Expand Down
61 changes: 53 additions & 8 deletions macbox
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ eval "$_env"
: "${MACBOX_GUEST_USER:=dev}" "${MACBOX_CPUS:=8}" "${MACBOX_MEMORY:=12G}" "${MACBOX_DISK_SIZE:=160G}"
: "${MACBOX_RESOLUTION:=1920x1080}" "${MACBOX_REFRESH:=60}" "${MACBOX_CPUSET:=}"
: "${MACBOX_RENDER_NODE:=/dev/dri/renderD128}" "${MACBOX_DISK_CACHE:=none}" "${MACBOX_GPU_TUNING:=auto}"
: "${MACBOX_COHERENT:=auto}" "${MACBOX_VIDEO:=off}"
: "${MACBOX_COHERENT:=auto}" "${MACBOX_VIDEO:=off}" "${MACBOX_VIEW_SWITCH:=off}"
: "${MACBOX_SIM_PREFIX:=macbox}" "${MACBOX_POOL:=full slim-1 slim-2 sharp small}"
: "${MACBOX_T3_HOST_ID:=$MACBOX_SSH_HOST}" "${MACBOX_T3_SETTINGS:=$HOME/.t3/userdata/settings.json}"
DOCKER="${MACBOX_DOCKER:-docker}"
Expand Down Expand Up @@ -59,9 +59,10 @@ container_start() {
local e dev=(--device /dev/kvm --device "$MACBOX_RENDER_NODE") vol=() wl
mapfile -t e < <(cenv)
[ -e /dev/udmabuf ] && dev+=(--device /dev/udmabuf) # AMD GPUs import guest memory through it
if [ "$(view)" = local ]; then
# With MACBOX_VIEW_SWITCH=on the host's desktop is reachable whatever the view, for a later move.
if [ "$(view)" = local ] || [ "$MACBOX_VIEW_SWITCH" = on ]; then
if wl=$(host_wayland); then vol=(-v "$wl:/tmp/host-wayland/wayland-0")
else warn "view local, but this shell has no Wayland session (WAYLAND_DISPLAY): the window goes to the browser stream"; fi
elif [ "$(view)" = local ]; then warn "view local, but this shell has no Wayland session (WAYLAND_DISPLAY): the window goes to the browser stream"; fi
fi
# seccomp/AppArmor unconfined: passt, the VM's network, needs a user namespace.
$DOCKER run -d --name "$C" --init "${e[@]}" \
Expand All @@ -74,6 +75,29 @@ vm_exists() { [ -f "$VMDIR/vm.toml" ]; }
vm_running() { container_up && ctl list 2>/dev/null | grep -qE "^${MACBOX_VM}[[:space:]]+running"; }
qemu_pid() { $DOCKER top "$C" -eo pid,args 2>/dev/null | awk '/qemu-system-x86_64/ {print $1; exit}'; }
view() { cat "$RUN/view" 2>/dev/null || echo stream; }
stream_socket() { # sway's socket in the container, the stream's (display-up.sh starts it if needed)
echo "/tmp/xdg/$(in_c "$REPO/src/container/display-up.sh" | sed -n 's/^WAYLAND_DISPLAY=//p')"

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 Propagate display-stack startup failures from stream_socket

With MACBOX_VIEW_SWITCH=on, if display-up.sh fails (for example, while installing Selkies on first use), the enclosing echo masks the failed pipeline and successfully returns /tmp/xdg/ instead of a socket. Consequently, cmd_up writes that directory into run/compositor, starts the VM without a usable display, and reports success; previously, the direct assignment propagated the failure and stopped startup. This was reproduced with a failing in_c stub under set -euo pipefail. Capture and check the pipeline's result separately before printing the socket path.

Useful? React with 👍 / 👎.

}
# Moves the running VM's window to view $1 without a restart (MACBOX_VIEW_SWITCH=on): Reims reads
# the socket from run/compositor once a second and says where its windows are in run/compositor.on.
view_move() {
local to _
case "$1" in
local) in_c test -S /tmp/host-wayland/wayland-0 ||
die "this desktop isn't reachable from the container (it started without WAYLAND_DISPLAY): macbox down && macbox up from a shell on the desktop"
to=/tmp/host-wayland/wayland-0 ;;
stream) to=$(stream_socket) ;;
esac
[ "$(cat "$RUN/compositor.on" 2>/dev/null)" = "$to" ] && { echo "$1" >"$RUN/view"; say "view: $1 (already)"; return 0; }

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 Replace pending compositor requests before returning already

If a user interrupts macbox view stream before Reims processes its request and then runs macbox view local, compositor.on can still name the local socket while compositor requests the stream. This early return reports local (already) and updates run/view without replacing the pending stream request, so Reims subsequently moves the window to the stream despite the successful local command. The same race occurs with overlapping opposite-view commands. Write the requested socket even when the acknowledgement already matches, so a previous pending request cannot override the latest selection.

Useful? React with 👍 / 👎.

echo "$to" >"$RUN/compositor.tmp" && mv "$RUN/compositor.tmp" "$RUN/compositor"
for _ in $(seq 40); do
if [ "$(cat "$RUN/compositor.on" 2>/dev/null)" = "$to" ]; then
echo "$1" >"$RUN/view"; say "view: $1, no restart"; return 0
fi
sleep 0.5
done
die "the window didn't move to $to in 20 s (macbox logs qemu); run/compositor.on: $(cat "$RUN/compositor.on" 2>/dev/null)"
}
resolution() { cat "$RUN/resolution" 2>/dev/null || echo "$MACBOX_RESOLUTION"; }
build_id() { readlink "$DATA/qemu/current" 2>/dev/null || true; }
ssh_ok() { ssh -o ConnectTimeout=5 -o BatchMode=yes "$MACBOX_SSH_HOST" true >/dev/null 2>&1; }
Expand Down Expand Up @@ -215,6 +239,9 @@ MACBOX_COHERENT=$MACBOX_COHERENT
# on: Reims's hardware VideoToolbox (H.264/HEVC encode and decode on the host's GPU through VA-API)
# and M2 scaler devices; needs the video kexts in OpenCore (macbox video-kexts). off: as before
MACBOX_VIDEO=$MACBOX_VIDEO
# on: macbox view local|stream moves the running VM's window between this desktop and the browser
# stream without a restart (Reims's REIMS_VGPU_WINDOW_COMPOSITOR_FILE); off: view restarts the VM
MACBOX_VIEW_SWITCH=$MACBOX_VIEW_SWITCH
# iOS Simulator pool: names are "<device> (<prefix> <label>)"
MACBOX_SIM_PREFIX=$MACBOX_SIM_PREFIX
MACBOX_POOL="$MACBOX_POOL"
Expand Down Expand Up @@ -358,15 +385,24 @@ cmd_up() {
vm_exists || die "no VM yet: macbox create"
rm -f "$RUN/stopping"
container_start
local wd
if in_c test -S /tmp/host-wayland/wayland-0; then
local wd sw=()
if [ "$MACBOX_VIEW_SWITCH" = on ]; then
# Both places run, and the window moves between them (view_move).
wd=$(stream_socket)
[ "$(view)" = local ] && in_c test -S /tmp/host-wayland/wayland-0 && wd=/tmp/host-wayland/wayland-0
vm_running || echo "$wd" >"$RUN/compositor"
sw=(--env "REIMS_VGPU_WINDOW_COMPOSITOR_FILE=$RUN/compositor")
elif in_c test -S /tmp/host-wayland/wayland-0; then
wd=/tmp/host-wayland/wayland-0
in_c mkdir -p -m 700 /tmp/xdg # the window's XDG_RUNTIME_DIR (vm.toml), which sway makes otherwise
else
wd=$(in_c "$REPO/src/container/display-up.sh" | sed -n 's/^WAYLAND_DISPLAY=//p')
fi
# Switched off again: Reims connects as before (an empty value is unset).
[ ${#sw[@]} -eq 0 ] && grep -q REIMS_VGPU_WINDOW_COMPOSITOR_FILE "$VMDIR/vm.toml" 2>/dev/null &&
sw=(--env "REIMS_VGPU_WINDOW_COMPOSITOR_FILE=")
if ! vm_running; then
ctl set "$MACBOX_VM" --env "WAYLAND_DISPLAY=$wd" --extra-args "$(qemu_extra)" >/dev/null
ctl set "$MACBOX_VM" --env "WAYLAND_DISPLAY=$wd" "${sw[@]}" --extra-args "$(qemu_extra)" >/dev/null
apply_tuning
ctl start "$MACBOX_VM"
fi
Expand Down Expand Up @@ -397,8 +433,14 @@ cmd_status() {
ctl list | sed 's/^/ /'
local pid; pid=$(qemu_pid)
[ -n "$pid" ] && ps -o pid,pcpu,rss,etime -p "$pid" | sed 's/^/ /'
if [ "$MACBOX_VIEW_SWITCH" = on ]; then
[ "$(cat "$RUN/compositor.on" 2>/dev/null)" = /tmp/host-wayland/wayland-0 ] &&
say " view: local (a window on the host's desktop; macbox view stream moves it, no restart)" ||
{ say " view: stream, http://127.0.0.1:$MACBOX_SCREEN_PORT/ (macbox view local moves it, no restart)"; in_c "$REPO/src/container/stream-up.sh" status | sed 's/^/ /'; }
else
in_c test -S /tmp/host-wayland/wayland-0 && say " view: local (a window on the host's desktop)" ||
{ say " view: stream, http://127.0.0.1:$MACBOX_SCREEN_PORT/"; in_c "$REPO/src/container/stream-up.sh" status | sed 's/^/ /'; }
fi
say " build: $(build_id)$(tuning_on && echo ', GPU tuning on' || echo ', GPU tuning off')"
say " coherent: $(coherent_state)"
say " screen: $(resolution)"
Expand Down Expand Up @@ -655,7 +697,8 @@ Setup (docs/setup.md):

Day to day:
macbox up | down | status | logs [qemu|selkies|sway]
macbox view local|stream the VM's window on this desktop, or in the browser stream
macbox view local|stream the VM's window on this desktop, or in the browser stream (a restart;
none with MACBOX_VIEW_SWITCH=on)
macbox stream selkies|novnc
macbox resolution WxH macOS's screen size (restarts a running VM)
macbox ssh [command]
Expand Down Expand Up @@ -685,7 +728,9 @@ case "$sub" in
view)
case "${1:-}" in
"") say "view: $(view)" ;;
local|stream) echo "$1" >"$RUN/view"; if container_up; then cmd_down; cmd_up; fi ;;
local|stream)
if [ "$MACBOX_VIEW_SWITCH" = on ] && vm_running; then view_move "$1"
else echo "$1" >"$RUN/view"; if container_up; then cmd_down; cmd_up; fi; fi ;;
*) die "usage: macbox view [local|stream]" ;;
esac ;;
stream) container_up || die "the container isn't running"; in_c "$REPO/src/container/stream-up.sh" "${1:-status}" ;;
Expand Down
3 changes: 2 additions & 1 deletion src/patches/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ is in [docs/performance.md](../../docs/performance.md#gpu-tuning-switches).
| 0062, 0068, 0076, 0077, 0080, 0081, 0083, 0084, 0086, 0090 experiments | `xr_unused_bits_off`, `surface_coherent_writer_wins`, `M2V_FLAT_TILE`, `shared_ccs`, `host_mutable`, `batch_end_light`, `view_render_direct`, `precise_barriers`, `checks_first`: live switches, all off. Most are in [docs/performance.md](../../docs/performance.md#tried-no-gain) |
| 0047, 0048, 0052–0057, 0063–0067, 0071–0075, 0078, 0079, 0082, 0086–0089, 0091 diagnostics | the pass timer's units and censuses, logs of views, twins, barriers and the scheduler, counters of why shadows copy back, and `M2V_PENDING_AUDIT` (command buffers begun while their submission is pending). Off unless their variable is set |

## Reims vGPU (on 7198fe6), 35 patches
## Reims vGPU (on 7198fe6), 36 patches

| Patches | What they do |
|---|---|
Expand All @@ -62,6 +62,7 @@ is in [docs/performance.md](../../docs/performance.md#gpu-tuning-switches).
| 0030 `REIMS_VGPU_PAGED_BUFFER_BY_PAGES` | finds kept paged buffers by their guest pages; off |
| 0031–0033 staged page-ups | `REIMS_VGPU_STAGED_PAGE_UP`, `REIMS_VGPU_STAGED_ZERO`: a new texture's first page-up copies its pages into a staging buffer (one copy per run) when no live view covers them, and pages of zeros write nothing. Before, each page run took its own mapping: 55k a second and a storm of TLB shootdowns; the simulator went from 89 to 101 fps. On with Coherent |
| 0034, 0035 the detach check | Every submission is checked, on metal2vulkan's scheduler thread, against the objects detached now. That list is now made once per change (a detach, an attach or a release), sorted, and asked by binary search (metal2vulkan 0100). Before, it was made again for every check and scanned: 18–24% of that thread's time. On by default. Live `detached_sorted=0` brings back the check as before, for an A/B in one boot. Measured: 1 simulator +3.5%, 3 simulators +5.3% ([performance.md](../../docs/performance.md#several-simulators-at-once-and-the-desktop-under-load)). |
| 0036 `REIMS_VGPU_WINDOW_COMPOSITOR_FILE` | the windows move to another Wayland compositor while the VM runs: the file names the socket. Reims connects to it itself and hands SDL the connection; when the file changes, each window lets its input go, its render thread lets the swapchain and surface go, SDL's video restarts on the new socket, and the windows open there. On failure they go back. `<file>.on` says where they are. Off unless set; `MACBOX_VIEW_SWITCH=on` sets it. |

## QEMU (`vendor/qemu` at bd95509, github.com/steelbrain/qemu-reims-vgpu), 14 patches

Expand Down
Loading
Loading