Userspace DRM/KMS/GBM. Mode A in-window Metal. Mode B Classic fullscreen Metal. TrollStore IOMFB sink.

iLand is Wawona's userspace DRM/KMS/GBM. It emulates the Linux graphics objects a compositor and clients already know (connector, CRTC, plane, framebuffer, GBM bo) and presents them on the host through IOSurface + Metal (Apple) or AHardwareBuffer (Android).

That is a runtime substitution of the platform under the client. It is not a kernel driver, not a /dev/dri node, and not a video capture of Aqua.

Zero-copy protocol matrix (zwp_linux_dmabuf_v1, modifiers, sinks): linux-dmabuf.

Never a real DRM device

Wawona must never open kernel DRM:

  • No real /dev/dri
  • No real /dev/kgsl
  • No forwarding of kernel DRM/KMS/KGSL ioctls
  • No kernel modules or kernel patches

Clients and nested compositors still call the usual KMS/GBM entry points. Those calls terminate inside iland. The objects they get are userspace. Present is Metal (or the Android buffer path), not a physical CRTC programmed by XNU.

Mode B's package name iland-baremetal is a legacy label for the macOS Desktop dylib. It is still userspace.

Two present paths (do not conflate)

Mode A (default)Mode B (Desktop Replacement)
Artifactlibiland_userland.alibwayland-mac.dylib
Where it shipsEvery product target that can presentwawona-macos-desktop-host only (Contents/Library/Wawona/iland/)
Host compositorApple WindowServer / Aqua stays upWindowServer unloaded for that login (Classic)
Presentiland_drm_set_present_callback → WWNIlandPresenter / in-window CAMetalLayerMach IPC → framebufferd. Fullscreen Metal. No Aqua scene
LoadStatic linkDYLD_INSERT_LIBRARIES + Dobby on the session compositor exec only
SIPMay stay enabledMust be fully disabled (csrutil disable). Partial SIP is refused
App Store / PlayYesNo

Mode A is always required on macOS. Building or testing Mode B must never break in-window present.

Wawona Swinging Bridge is a different product (host apps become Wayland clients). It is not Desktop Replacement and not this dylib.

Mode A: iland inside a Cocoa window

SIP can stay on. Wawona is a normal macOS app. Nested weston/niri and Wayland clients render into iland's userspace KMS, then iland presents inside the Wawona window (AppKit + Metal). WindowServer is still compositing Aqua around that window. That is the store-shaped / notarized .#wawona-macos path.

On App Store / TestFlight iOS family and on Android Mode A, present is in-process to the host UI toolkit's Metal / AHardwareBuffer surface (CAMetalLayer or ANativeWindow).

iOS / iPadOS Mode B present: IOMobileFramebuffer

TrollStore (.tipa + ldid) and Sileo Mode B may present via IOMobileFramebuffer for in-app Desktop / LockScreen own-display. That sink is never linked into the store IPA. TrollStore does not add Swinging Bridge or ElleKit; Sileo does. See Mode A and Mode B and Desktop.

SinkWhen
CAMetalLayerMode A (store / in-window)
IOMobileFramebufferiOS/iPadOS TrollStore and Sileo Mode B
framebufferd (Mach)macOS Classic Desktop only

Mode B: Desktop Replacement as a custom framebuffer

Classic Desktop Replacement on wawona-macos-desktop-host is how macOS gets closest to "real" DRM/KMS/GBM without a kernel node and without drawing Aqua.

After Replace now (and only then):

  1. IOWatchdog Path B (iowatchdog-tools) has a sticky Disable ACK. Unloading watchdogd without that panics on macOS 26. See Desktop and LockScreen.
  2. Apple WindowServer is not running for that session. There is no Aqua desktop to composite. Wawona does not render Finder, Dock, or the menu bar.
  3. iGetty owns virtual terminals (igettyd, Doorman session, F1-F9). The Desktop machine is a native weston or niri session, not a Linux VM.
  4. The Mode B dylib (libwayland-mac.dylib from iLand iland-baremetal / macos-baremetal.nix) is prefixed on the session compositor command only. Never export DYLD_INSERT_LIBRARIES in the login shell (Apple /bin/* is arm64e; a global export kills date / launchctl).
  5. That compositor talks iland DRM: weston --backend=drm, niri NIRI_BACKEND=tty. Clients allocate GBM/KMS as they would on Linux. iland implements the device. Present is a fullscreen Metal path (framebufferd over Mach), not a CAMetalLayer inside an Aqua window.

So: Linux-shaped DRM/KMS/GBM API in userspace, mapped to a fullscreen Metal view, with WindowServer gone. Logout (or Ctrl+Option+Backspace) returns Aqua. Next login does not auto-engage.

KEEP_WS (Wawona --mode-b-probe) leaves WindowServer up on purpose. That is a probe, not Classic. Path C (parked WindowServer for Swinging Bridge + Desktop together) is still planned.

Who owns which piece

PieceRepoRole
Mode A archiveiLandlibiland_userland.a, in-window Metal present
Mode B dylibiLand iland-baremetallibwayland-mac.dylib. Intercepts the DRM/GBM ABI; Mach → framebufferd
IOWatchdog Path Biowatchdog-toolsSticky Disable ACK before unloading watchdogd
VTs / gettyiGettyigettyd, Doorman session, Ctrl+Option+F1-F9
SIP, Settings, Take OverWawonaWWNSipStatus, WWNDesktopReplacementController, WWNWaypipeRunner
Session weston DRMrepo.wawona.io deb catalog--backend=drm over iland. Weston ships as a deb; no separate fork repo.
Session niri DRMrepo.wawona.io deb catalogNIRI_BACKEND=tty after Classic. Niri ships as a deb; no separate fork repo.

Friends how-to, install sync, and safety forbids: Desktop and LockScreen. After you change this dylib or iGetty, run nix run .#install or open the new desktop-host app once. See Compilation: install and updates.

Inner weston/niri started inside a Classic session are ordinary Wayland clients of that session's socket. Do not nest the session compositor on Wawona (there is no host Wayland after Classic). Do not sudo niri / sudo weston.

Graphics stack (L1)

L1 owns ANGLE, SwiftShader, MoltenVK, KosmicKrisp, Turnip hooks. Substrate 2D (cairo, pango, pixman) stays in wwn-toolchain (L0). Consumers that need GLES/Vulkan merge the iland fragment. tvOS ships ANGLE (OpenGL ES to Metal) and MoltenVK (Vulkan to Metal). watchOS has no public Metal and stays on the SHM/CPU fallback. See Graphics and DAG.

Canonical engineering notes: iland-mode-a-b-desktop.md. Dmabuf / IOMFB completion gates: linux-dmabuf.