NextBSD mach_port MIG client kernel + libmach

Half of libmach’s mach_port subsystem returns KERN_SUCCESS without doing anything. This is the plan to replace it with generated MIG stubs, in the layering Apple actually uses — written after two runtime probes overturned the previous draft.

What changed — and what the previous draft got wrong

An earlier version of this page recommended wiring a syscall trap and stated that a MIG client “cannot be generated.” That recommendation is withdrawn. The distinction matters, because one half of the claim was true and the other was not:

Recorded deliberately: the deferral was the actual error. A one-afternoon runtime probe would have settled the architecture before any of the design work around it, and the comment that caused the deferral describes a different code path.

Was this ever MIG? — checked, not assumed

A fair challenge before committing: did we once use MIG for these calls and retreat to traps because making MIG work was too hard? If so, this plan would be walking back into a known dead end. Searched across all 578 commits of nextbsd-userland:

The traps were never a retreat from MIG — MIG was never tried here. The traps came first (9917b83, “libmach userland shim for the wired Mach trap family”), and the stubs were link-stage scaffolding to get the vendored launchd to build. They were never revisited. The one commit that superficially looks like a retreat — 176c543, “drop the mach.ko trap multiplexor for dedicated syscalls” — is about syscall slot allocation, folding five ops out from behind one multiplexed slot. It does not mention MIG.

Is Apple retiring MIG in favour of XPC?

Not for this layer, and the distinction is worth stating precisely because the headline impression is the opposite.

Where the impression is right: XPC has largely displaced MIG for new userland IPC — app↔daemon and daemon↔daemon. That is what Apple documents for third parties, and where their own newer services go.

Where it does not apply: XPC is layered on Mach messaging, not a replacement for it, and there is no XPC path to the kernel. Kernel RPC — mach_port_*, task_*, host_*, vm_* — is MIG and remains MIG. So is exception handling (exc.defs, mach_exc.defs). Measured against Apple’s current sources:

• Apple still ships and versions MIG itself — bootstrap_cmds-138, tagged 2025-04-30.
• Current XNU carries 46 .defs files, and mach_port.defs is listed in MIG_DEFS in osfmk/mach/Makefile — so Apple generates mach_port_server.c from it at build time. Path A restores precisely Apple’s arrangement rather than inventing one.
• Apple keeps adding MIG interfaces, not just maintaining old ones: mach_eventlink.defs, arcade_register.defs, memory_error_notification.defs, mach_voucher*.defs, iocompressionstats_notification.defs are all modern additions.

So this is not investment in a deprecated technology. It is the one layer XPC does not reach.

And in our own tree, the two already coexist — by design

MIG and XPC are not alternatives, and getting MIG working does not make libxpc droppable. They sit at different layers and answer different questions. MIG is compile-time-typed RPC whose interface is fixed in a .defs; XPC is dynamically typed, self-describing dictionaries with no interface definition at all. xpc_dictionary_get_string(msg, key) for an arbitrary runtime key is not expressible in MIG, by construction.

The tree already carries 24 .defs files — configd, ipconfigd, notifyd, ASL, WLAN, kext_tools, libdispatch’s firehose, and seven for launchd alone (job.defs, job_forward.defs, job_reply.defs, protocol_jobmgr.defs, helper.defs, internal.defs, notify.defs). That same launchd holds 178 XPC references (xpc_domain, xpc_service, xpc_bootstrapper, xpc_singleton_domain). The XPC layer rides on the MIG control protocol, exactly as it does at Apple. src/libxpc is the iXsystems 2014–15 implementation, ~13k LOC, serialising nvlists over raw mach_msg — a real implementation with real consumers (syslog 84 references, Libnotify 58), not a stub layer.

The experiment

Two C programs, compiled natively on the VM with /usr/local/bin/clang19 against /usr/lib/system/libsystem_kernel.so.0. No kernel build, no reboot, nothing that could damage the host — worst case the test process dies.

Probe 1 — simple reply

mach_port_get_attributes, msgh_id 3217, MACH_PORT_RECEIVE_STATUS. The message is hand-built to the shape the frozen server demands, which is the inverse of modern MIG output: MACH_MSGH_BITS_COMPLEX set with a descriptor count of zero.

sizeof(Request) = 48   (server expects 48 from userland)
allocated probe port: 0x11
sending msgh_id=3217 COMPLEX, desc_count=0, size=48 ...
mach_msg returned 0x0 (0)
reply msgh_id  = 3317   (expect 3317)
RetCode        = 0
outCnt         = 10
  mps_pset=0 seqno=0 mscount=0 qlimit=5 MSGCOUNT=0

RESULT: kernel MIG WORKS

qlimit=5 is MACH_PORT_QLIMIT_DEFAULT — real kernel state, not a zeroed buffer. That distinction is what makes this a result rather than a coincidence.

Probe 2 — complex reply with out-of-line memory

mach_port_get_set_status, msgh_id 3214 — the exact call libmach fakes. A port set is populated with a known member via the real mach_port_move_member trap, then the kernel is asked for its membership back. This exercises vm_map_copyin in the kernel and the OOL copyout into our address space, which probe 1 did not.

pset=0x11  member=0x12
move_member -> 0x0 (ok)
sending msgid 3214 for pset 0x11 ...
mach_msg -> 0x0
reply id=3314  size=56  complex=yes  desc_count=1
membersCnt=1  ool.size=4  ool.address=0x1000
  member[0] = 0x12 <-- the port we inserted

RESULT: OOL round-trip WORKS -- kernel returned the real member

What Apple actually does

The guiding requirement is to use MIG where Apple does. Apple’s own sources answer this precisely, and the answer is not “everywhere”.

MIG is the floor; traps are an accelerator

Every mach_port routine in libsyscall has a generated MIG client named _kernelrpc_mach_port_*. Some routines additionally have a trap, which is tried first and falls back to MIG on failure:

/* xnu/libsyscall/mach/mach_port.c */
mach_port_allocate(ipc_space_t task, mach_port_right_t right, mach_port_name_t *name)
{
        kern_return_t rv;

        rv = _kernelrpc_mach_port_allocate_trap(task, right, name);

        if (rv == MACH_SEND_INVALID_DEST) {
                rv = _kernelrpc_mach_port_allocate(task, right, name);   /* MIG */
        }

        return rv;
}

Routines returning arrays are pure MIG — necessarily

mach_port_names and mach_port_get_set_status have no trap at all at Apple. You cannot return a variable-length array through a register-based trap interface. This is precisely why our stub had to invent an empty list rather than do something useful:

mach_port_get_set_status(ipc_space_t task, mach_port_name_t name,
    mach_port_name_array_t *members, mach_msg_type_number_t *membersCnt)
{
        kern_return_t rv;

        rv = _kernelrpc_mach_port_get_set_status(task, name, members, membersCnt);

        return rv;      /* MIG only. No trap exists. */
}

Apple has run our exact situation, and chose MIG

In mach_port_get_attributes, Apple handles a kernel whose trap does not exist yet by mapping the failure onto MACH_SEND_INVALID_DEST so control falls through to MIG:

rv = _kernelrpc_mach_port_get_attributes_trap(task, name, flavor,
    port_info_out, port_info_outCnt);

#ifdef __x86_64__
/* REMOVE once XBS kernel has new trap */
if (rv == ((1 << 24) | 40)) {   /* see mach/i386/syscall_sw.h */
        rv = MACH_SEND_INVALID_DEST;
}
#endif

if (rv == MACH_SEND_INVALID_DEST) {
        rv = _kernelrpc_mach_port_get_attributes(task, name, flavor,
            port_info_out, port_info_outCnt);
}

MIG is the always-correct path. The trap is an optimisation that is permitted to be absent. A NextBSD that has traps but no MIG has built the fast lane without the road.

The audit

Every NextBSD trap, checked against Apple’s real trap table

Compared against the 130 entries in xnu/osfmk/kern/syscall_sw.c. Bare-name matching gives false negatives here — Apple names the mach_port entries _kernelrpc_…_trap — so the comparison below matches both forms.

The stubs that fabricate success

Roughly 18 entry points in mach_traps.c return KERN_SUCCESS having done nothing. The mach_port ones:

mach_port_get_set_status   <-- kills on-demand Mach launch in launchd
mach_port_type             <-- Apple traps this, with MIG fallback
mach_port_mod_refs         <-- silently no-ops reference counting
mach_port_set_mscount
mach_port_get_context
mach_port_set_context
mach_port_construct
mach_port_destruct

The current get_set_status, in full — this is the whole reason on-demand launch is dead:

mach_port_get_set_status(mach_port_name_t task, mach_port_name_t name,
    mach_port_name_array_t *members, mach_msg_type_number_t *membersCnt)
{
        (void)task; (void)name;
        if (members != NULL)
                *members = NULL;
        if (membersCnt != NULL)
                *membersCnt = 0;
        return KERN_SUCCESS;
}

Nothing currently speaks this wire format

A code search for MACH_MSGH_BITS_COMPLEX across nextbsd-userland returns zero hits. No userland code hand-builds messages to the mach_port subsystem, so regenerating the server cannot break an existing caller. This is what makes a kernel-side regeneration tractable rather than reckless.

Plan

mach_port_get_set_status(mach_task_self(), demand_port_set, &members, &membersCnt)
        → stub returns membersCnt = 0     ⇒ the loop body never executes

for (i = 0; i < membersCnt; i++) {
        mach_port_get_attributes(..., MACH_PORT_RECEIVE_STATUS, &status, &statusCnt)
                → stub returns KERN_RESOURCE_SHORTAGE   ⇒ continue, every member skipped
        if (status.mps_msgcount) { ...dispatch the job... }
}

vm_deallocate(mach_task_self(), (vm_address_t)members, ...)
        → no-op                            ⇒ leaks once get_set_status is real

Risks

Open calls

Measured on gershwin-on-nextbsd. Apple sources: apple-oss-distributions/xnu, libsyscall/mach/mach_port.c and osfmk/kern/syscall_sw.c. Claims from measurement are marked apart from claims from reasoning throughout; where this page contradicts an earlier draft, the earlier draft is wrong and §“What changed” says why.