Mach traps: complete slot catalog and operation boundaries

Interface overview · Machine entry paths · IPC · VM

The common table has 128 slots, indexed 0–127. There are 62 potentially named operations: 60 unconditional named slots, slot 47 when __LP64__ || __arm64__, and slot 63 when __LP64__. Thus an LP64 build has 62 named/66 invalid entries; ARM64 without LP64 has 61/67; a build satisfying neither condition has 60/68. These are table counts, not a claim that every named operation performs useful work in every configuration. Four named backing-store interfaces are unconditional ENOTSUP stubs, and other handlers have configuration-dependent bodies. Table, table size and entry layout.

The catalog below preserves every slot, exact argument counts and mungers, kernel argument-field order/types, implementation location, and operation purpose. It is generated from this checkout by build_mach_trap_catalog.py, with curated descriptions checked against selected bodies. The machine-entry companion explains how a slot becomes an ARM64 negative selector or an x86 class/number, and why an invalid slot generally raises a syscall exception before kern_invalid() is invoked.

Complete table: all 128 slots

The ABI column is argument count / 32-bit word count / munger suffix exactly as stored in the table; — means no munger. port marks the table’s direct port-name return flag. Argument declarations below are kernel argument-structure fields, in order; a user_addr_t is a userspace pointer value, not a kernel pointer. Source links on slot numbers identify the exact table entries. Conditional alternatives are preserved rather than evaluated for this host.

Slots 0–31

Slots 32–63

Slots 64–95

Slots 96–127

ABI metadata and historical discrepancies

The table stores a function pointer, logical argument count, count of 32-bit words, optional 32-bit munger, and a flag for direct port-name results. Six entries set that result flag: 26, 27, 28, 29, 50, and 91. Dispatchers use it when converting policy denial to MACH_PORT_NULL. It does not mean every other handler returns a conventional kern_return_t: swtch returns a boolean, and the retained macx_* bodies use BSD-valued errors through a Mach-table route. Entry definition, filter return handling.

The kernel's argument structures are the decoder contract; library prototypes and assembly macros are additional evidence rather than substitutes. This matters in several visible cases:

The 32-bit munger bodies make the distinction concrete: munge_wwww widens four words, while munge_wlll reads its last 64-bit value beginning at input word five. Munger implementations, three-long form.

Sources: kernel message structures, stub list, unused ninth-argument comment, swtch body, slot 76, timer structure, timer/compatibility stubs. These are source observations, not fixes or claims that every compatibility path is exercised in a shipped build. Modern ARM64 argument gathering copies 64-bit slots; x86 retains both 64-bit gathering and a 32-bit copy/munge route. See machine entry points.

Current-task fast traps and MIG fallback

The _kernelrpc_*_trap family is not a general in-kernel MIG demultiplexer. Its handlers usually recognize a capability for the current task, then call a VM or IPC-space operation directly. An unsupported destination produces MACH_SEND_INVALID_DEST, allowing the library to choose its message-based _kernelrpc_* implementation. A real operation failure, such as invalid arguments or failed user copy, does not universally trigger the fallback. VM trap bodies, port trap bodies, message interface catalog.

current-task VM allocation fast path

_kernelrpc_mach_vm_allocate_trap(struct _kernelrpc_mach_vm_allocate_trap_args *args)
{
	mach_vm_offset_t addr;
	task_t task = port_name_to_current_task_noref(args->target);
	int rv = MACH_SEND_INVALID_DEST;

	if (task) {
		if ((rv = mach_copyin(args->addr, (char *)&addr, sizeof(addr)))) {
			goto done;
		}

		rv = mach_vm_allocate_external(task->map, &addr, args->size, args->flags);
		if (rv == KERN_SUCCESS) {
			rv = mach_copyout(&addr, args->addr, sizeof(addr));
		}
	}

done:
	return rv;
}

The corresponding library branch is equally specific:

VM allocation fallback condition

	rv = _kernelrpc_mach_vm_allocate_trap(target, address, size, flags);

	if (rv == MACH_SEND_INVALID_DEST) {
		rv = _kernelrpc_mach_vm_allocate(target, address, size, flags);
	}

Mermaid source

flowchart TD
    L["mach_vm_allocate / port wrapper"] --> T["direct trap"]
    T --> C{"current-task fast target accepted?"}
    C -->|yes| H["copy user inputs → VM / IPC implementation → copy outputs"]
    C -->|no| I["MACH_SEND_INVALID_DEST"]
    I --> G["library MIG client creates message"]
    G --> M["mach_msg transport trap"]
    M --> K["destination kobject / MIG routine dispatch"]
    H --> R["return operation result"]

The fast-path scope has real ownership consequences. mach_port_insert_right uses a same-name MAKE_SEND/COPY_SEND shortcut; otherwise it copies in a right, converts the disposition, invokes insertion, and destroys the acquired right if insertion fails. Notification registration similarly converts/acquires a send-once right and may copy a previous notification right into the caller's space. A copyout error is later than the kernel object transition: allocation and port-construction bodies do not show a universal rollback of a successfully created object when the final scalar copyout fails. Right insertion cleanup, notification ownership, port construction, rights lifecycle.

Message transport, packed ABI, and interruption

Slot 47's eight logical arguments are eight 64-bit fields, with several packing two 32-bit values. The kernel reconstructs the message header from these scalars; descriptor/body data still comes from the user message or vectors. The ordinary nonvector interpretation is:

Vector mode changes how size/count fields are interpreted and obtains message/auxiliary vector information first. The kernel applies current-task options and ipc_preflight_msg_option64(), performs send if requested, and only proceeds to receive if send succeeded. A bad receive vector does not necessarily prevent a valid send in a combined operation. Packed decoding and send, message ownership guide.

header reconstruction from packed trap fields

		mach_msg_send_uctx_t send_uctx = {
			.send_header = {
				.msgh_bits         = (mach_msg_bits_t) (mb_ss),
				.msgh_size         = 0,
				.msgh_remote_port  = (mach_port_name_t)(mr_lp),
				.msgh_local_port   = (mach_port_name_t)(mr_lp >> 32),
				.msgh_voucher_port = (mach_port_name_t)(mv_id),
				.msgh_id           = (mach_msg_id_t)   (mv_id >> 32),
			},
			.send_dsc_count = (mach_msg_size_t)dc_rn,
		};

mach_msg2_internal() removes library-only option bits and retries an interrupted send when allowed. After an interrupted receive, it clears the send action and send size before retrying. Reissuing the original combined operation could otherwise resend a request whose send already completed. Library retry body, receive phase and compensation.

Slots 31 and 32 remain named on all table configurations, but their meaningful legacy body is selected by IPC_HAS_LEGACY_MACH_MSG_TRAP, defined here only for XNU_TARGET_OS_OSX. Otherwise the overwrite handler returns KERN_NOT_SUPPORTED; slot 31 delegates to it. Thus the count of installed function names is not the count of supported transports. Legacy configuration, disabled result.

Message IDs belong to a separate namespace. A request using slot 47 may target a user server, a kernel kobject, or another supported destination; only later IPC/kobject dispatch selects the appropriate service routine. The MIG catalog inventories those messages and generated/external boundaries. The transport trap number does not identify a particular MIG operation.

Semaphores, scheduler calls, and timer ports

The semaphore traps convert port names to retained semaphore objects before using the shared wait/signal machinery. A targeted signal also resolves and later releases a thread reference; a null target means “choose an existing waiter without pre-posting” in that particular operation. Timed waits validate the timespec; {0,0} selects nonblocking behavior rather than an arbitrary already-expired timestamp. Wait handlers supply thread_syscall_return as their continuation, so the blocked operation can complete without returning through its original C frame. Targeted signal, wait entry, timed-wait conversion, wait/turnstile mechanisms.

swtch and swtch_pri ask scheduler policy whether yielding is useful; swtch_pri adds temporary depression and removes it in its continuation. pfz_exit currently just succeeds: its purpose is to enter/exit the kernel so pending AST processing can run, not to invoke a hidden scheduler-specific handler in the trap body. thread_switch has a richer option/hint path. Yield operations, thread switch, scheduler guide.

Timer creation allocates a timer object, initializes a thread call, preallocates a reusable expiration message, and allocates a receive-right port carrying the timer label. The timer retains its own send right. Arming/canceling operate through this port identity; destruction validates the receive right and timer label. Final timer teardown coordinates with an active callback, so “cancel” and “destroy the port/object” are different lifetime operations. Creation, label deallocation, destroy, arm/cancel.

Exclaves slot 88: all 26 secondary operations

operation_and_flags uses the upper byte for the operation and the lower 24 bits for flags; this trap currently rejects nonzero flags. CONFIG_EXCLAVES == 0 leaves the slot present but returns KERN_NOT_SUPPORTED. With the feature enabled, the body applies operation-specific privilege checks, waits for ExclaveCore boot for the ordinary route, and interprets the other seven arguments according to the selected operation. Boot is handled by an earlier privilege-gated branch. Encoding enum/macros, entry privilege/configuration, disabled body.

The following table inventories every non-sentinel enum operation. Field names refer to the slot-88 kernel structure above; the local handler may rename identifier to an offset and param1/param2 to secondary lengths/offsets. These are operation-specific uses, not additional trap numbers.

Operation zero, the LAST sentinel, and other unhandled selectors reach invalid-argument handling after the applicable front-end checks. The catalog establishes local argument roles and dispatch, not the secure service's complete implementation. Continue with Exclaves resources and secure execution for resource, thread, scheduler and external-boundary ownership.

IOKit, task access, and retained stubs

Slot 100 is a dispatch surface, not one universal driver operation. iokit_user_client_trap() interprets tagged reference bits, then either looks up a DriverKit uext reference and calls IOUserServerUEXTTrap, or resolves a current-task connection, applies an optional trap filter, and asks the user client for its target/trap at the supplied index. The six scalar payload arguments reach that selected member function. Lookup references are released by the appropriate path. The concrete target's index table remains provider-specific. IOKit trap body, DriverKit dispatch, user-client ownership.

PID/task conversion traps are implemented in BSD's process code even though they live in the Mach trap table. task_for_pid and debug-control access can obtain a task reference, drop a process reference before an access-server upcall, and apply credential/MAC/entitlement policy. A table slot or a PID is not authorization to receive a task-control right. pid_for_task consumes a task-name conversion and returns the PID through a userspace address; its body also handles a corpse task. Task-control entry, debug-control entry, PID conversion, process access policy.

Four historical macx_* handlers—swapon, swapoff, backing-store suspend and recovery—return ENOTSUP immediately. macx_triggers only supports compaction enable/disable flags via macx_backing_store_compaction(), whose disable behavior is further conditional on ARM64 macOS. Their old names/comments must not be used to document nonexistent modern swap-file operations. Stub/compaction bodies.

The deferred-reclamation accounting trap is installed only in LP64 table builds. In both feature configurations it first checks current-task identity and nonnull output addresses, returning MACH_SEND_INVALID_DEST or KERN_INVALID_ARGUMENT on those failures. After those checks, a build without CONFIG_DEFERRED_RECLAIM returns KERN_NOT_SUPPORTED. The enabled path invokes the accounting helper and attempts its two scalar copyouts only if that helper succeeds. It returns the helper's status rather than testing the copyout return values, so success cannot be read as a universal proof that both userspace outputs were written. Accounting trap.

Mach-named operations outside this table

mach_eventlink_signal, mach_eventlink_wait_until, and mach_eventlink_signal_wait_until are BSD slots 496, 497, and 498. The library explicitly explains the choice: these calls need a 64-bit register return containing count/result information, while ordinary Mach traps do not offer that result convention. The wrappers decode the error and, for wait operations, update the caller's count. Creation/association and other object operations can still be message interfaces. BSD declarations, library encoding boundary, BSD catalog, MIG catalog.

Likewise, direct ARM absolute/continuous-time selectors and x86 machine-dependent/diagnostic tables are cataloged in machine entry points, not counted as additional common Mach slots. A port's externalMethod selector, a voucher recipe command, and a MIG message ID are yet other namespaces selected after the top-level entry.

Inspection scope and regeneration

The generator updates only the marked all-slot table, preserving this explanatory material. Its purpose descriptions are curated from implementation bodies and must be reviewed if behavior changes; extraction is not semantic verification or a C preprocessor.