AST flavor reference: every bit and its consumer

This is the complete top-level AST namespace in this checkout, paired with concrete producers and consumers. The mechanism chapter explains propagation, interrupt levels, remote IPIs, continuation behavior, PFZ deferral, and the difference between a pending bit and an acknowledged operation. The definition contains 22 active individual bits, 5 named retired positions, 4 public composite masks, and the NONE/ALL constants. These counts describe the source namespace, not which features a particular kernel configuration enables. Authoritative definitions.

1. Active bits and service contracts

In the tables, T means membership in AST_PER_THREAD; C means a CPU-pending request outside that mask; R means a scheduling reason used by blocking/dispatch code. KPERF is deliberately marked T-storage/C-mask: its producer sets thread->ast, but the mask excludes it. “User dispatch” means the ordered, enabled-interrupt handler called from ast_taken_user(); MACH_EXCEPTION, DTRACE, TELEMETRY, KPERF, and DEBUG_ASSERT also belong to the restricted asynchronous-worker subset. Membership, dispatcher, asynchronous subset.

Scheduling reasons

The shared namespace is explicit technical debt in the header's “split the context switch and return-to-user AST namespaces” comment. A numeric reason in a scheduler trace therefore does not establish that the same bit was posted to cpu_pending_ast or dispatched as a callback. Namespace comment. See priority, QoS, and quanta and selection and context switching for the scheduler policies behind these reasons.

Thread control and policy callbacks

Accounting, exceptions, and resource pressure

Profiling, telemetry, and assertions

2. Composite masks, zero, and historical holes

The composites select different work; none should be treated as an interchangeable “all valid ASTs” mask:

ast.h, lines 139–152

#define AST_NONE                (UINT32_C(0))
#define AST_ALL                 (~AST_NONE)

#define AST_PREEMPTION  (AST_PREEMPT | AST_QUANTUM | AST_URGENT)
#define AST_SCHEDULING  (AST_PREEMPTION | AST_YIELD | AST_HANDOFF)

/* Per-thread ASTs follow the thread at context-switch time. */
#define AST_PER_THREAD  (AST_APC | AST_BSD | AST_MACF | AST_RESET_PCS | \
	AST_ARCADE | AST_LEDGER | AST_MACH_EXCEPTION | AST_SYNTHESIZE_MACH | \
	AST_LARGE_ENTER_TELEMETRY | AST_TELEMETRY | AST_KEVENT | \
	AST_PROC_RESOURCE | AST_DEBUG_ASSERT)

/* ASTs that can be skipped when checking if there's a reason to return to userspace */
#define AST_LAZY (AST_DEBUG_ASSERT)

• AST_PREEMPTION selects three scheduling bits: PREEMPT, QUANTUM, URGENT.
• AST_SCHEDULING adds HANDOFF and YIELD. It excludes REBALANCE and SFI even though scheduler code uses those reasons.
• AST_PER_THREAD lists 13 members, defining what ast_context() replaces on a CPU switch. It does not filter the incoming thread mask before ORing it into CPU state.
• AST_LAZY contains only DEBUG_ASSERT; a source search found no executable use beyond the definition.
• AST_NONE is zero. AST_ALL is the 32-bit complement of zero, including holes and unnamed bits; it is not an enumeration of supported callbacks.

These are direct readings of the definitions and context propagation. ASYNC_THREAD_ASTS_HANDLED, private to ast.c, is an additional five-member service subset, not another individual flavor or public header mask. Definition and use.

The comments are in ast.h:124–134. Bits 27–31 also have no named active member in this enum. A debugger decoding a raw mask must preserve unknown bits rather than assigning them one of these retired meanings. The statement concerns the displayed source definition, not a promise that every past or future XNU version shares it. Complete enum.

3. Kevent payload: three reasons under one top-level bit

The uint16_t payload is defined identically in the Mach and BSD AST headers. Producers merge reasons before posting the top-level bit; the consumer atomically detaches that reason set before executing it. Multiple posts of the same reason therefore need not produce multiple callback invocations. Definitions, BSD mirror, posting, exchange.

Dispatch order is REDRIVE, RETURN_TO_KERNEL, QUANTUM_EXPIRED, not bit order. act_clear_astkevent() can clear selected subsidiary reasons separately. This is a reason-set protocol, so callers must use the workqueue/kqueue state machine to decide whether useful work remains. Consumer, selective clear.

4. Telemetry payload: five triggers and two context flags

telemetry_ast_t has seven active bits. USER/KERNEL describe the context that caused a request; they are not independent top-level AST flavors or sample-count fields. Payload definition.

The generic sample call requires one of PMI/IO/VM_FAULT/PAGE_GRAB; MACF invokes its own sample path. USER/KERNEL alone do not reach either sampling call. A combined reason set can cause both paths. This is important when interpreting coalesced reasons: the payload describes requested work, not a queue of separate interrupt records. Exact consumer predicates.

telemetry.c, lines 494–503

	enum micro_snapshot_flags user_telemetry = (reasons & TELEMETRY_AST_USER) ? kUserMode : 0;
	enum micro_snapshot_flags microsnapshot_flags = record_type | user_telemetry;

	if ((reasons & TELEMETRY_AST_MACF) != 0) {
		telemetry_macf_take_sample(thread, microsnapshot_flags);
	}

	if ((reasons & (TELEMETRY_AST_PMI | TELEMETRY_AST_IO | TELEMETRY_AST_VM_FAULT | TELEMETRY_AST_PAGE_GRAB)) != 0) {
		telemetry_take_sample(thread, microsnapshot_flags);
	}

The header's VM/page-grab comments use CONFIG_MEMORY_MICROSTACKSHOTS and misspell the setter names; the implementation uses singular CONFIG_MEMORY_MICROSTACKSHOT and act_set_telemetry_ast_*. Follow the body when checking compilation or setting breakpoints. Header comments, actual functions.

5. Kperf payload and unrelated uses of the word AST

The low Kperf payload flags are T_KPERF_AST_CALLSTACK=1, T_KPERF_AST_DISPATCH=2, and T_KPC_ALLOC=4; T_KPERF_AST_ALL combines them. The field also carries action-ID and callstack-depth information using macros at offsets 18 and 24. Those macros are shift operations; this guide does not substitute an inferred packed-field mask for the actual code. kperf_ast_pend() merges flags and changes the action information only for the current thread, panicking for a remote target. Definitions, merge.

The KPC handler allocates a counter buffer if ALLOC is set; Kperf turns CALLSTACK/DISPATCH into sampler selections. Common dispatch then zeros the entire Kperf payload. Task-exec checks can skip sampling, and this dispatcher does not automatically retry a skipped sample. KPC buffer destruction has its own lifecycle. KPC handler and destruction, Kperf sampling, payload clear.

Names such as SCHED_AST_URGENT_SET_REASON_* are instrumentation reason constants for scheduler request bookkeeping; they are not additional AST bits. Similarly, kperf_exclaves_ast and its inspection callback do not add members to ast_t: the callback is invoked by Exclave inspection work and has its own payload/context. Scheduler reason enums, Exclaves callback. This reference exhausts the top-level enum and the specified sub-bit namespaces, not every symbol whose name contains the substring AST.

6. Inspection limits

All 22 active top-level bits were matched to their current consumer or scheduler-reason use, with representative producer bodies read for each. The three kevent bits, seven telemetry bits, three Kperf flag bits, public composites, private asynchronous subset, retired comments, and configuration guards were compared against the definitions above. The mechanism chapter's source table records the deeper paths reviewed.

This is a source walkthrough, not execution of a kernel configuration matrix. MAC policy providers, the Arcade validation service, and generated/user-side RPC behavior beyond visible call sites are not reconstructed. Feature guards in a shared enum do not establish that the corresponding feature is active on a particular machine, and an AST request does not promise successful external reporting or a retained reference to every object mentioned by its payload.