Goal: locate the request that did not arrive
A report that an interrupt never arrived combines several possible boundaries: generation, virtual pending state, delivery eligibility, guest acknowledgement, and handler execution. The objective is to identify the last state that actually changed and name the blocked boundary. Build on the previous four-state lesson. This selected GICv3 model uses two VMs and excludes priority competition, concentrating on recipient ownership, interrupt enable state, and the vCPU IRQ mask rather than pretending to implement the entire controller.
Before rewriting the guest's waiting loop, check whether the device requested service and which VM owns the pending request. Then inspect whether that context can currently run and receive it. More wakeup logging cannot repair a wrong recipient. The demonstration places input and pre- and post-acknowledgement state together. Follow the same request and owner across changes; two nearby timestamps are not sufficient evidence that one event caused the other.
Enable state and the IRQ mask are distinct gates
Enabling the interrupt does not ensure delivery if the vCPU masks IRQs. Clearing that mask does not help if the virtual interrupt itself remains disabled. In this model, enable controls acceptance of the selected source, while IRQ masking suppresses the vCPU's normal acceptance path. Real systems have additional group and priority conditions. Even in this reduced configuration, combining these two gates into one enabled variable makes useful diagnostic information disappear.
The normal case has pending set, enable set, IRQ masking clear, and a matching recipient and running VM. Change only enable, then restore it and change only the mask. Both experiments block acknowledgement while preserving waiting work. Unmasking does not generate a new request; it makes an existing request eligible to progress. If a repaired configuration works only after artificially generating another request, test whether the original pending condition was incorrectly lost while blocked.
Delivery belongs to a VM and vCPU context
VM A and VM B each have one vCPU in this lesson. A request addressed to A must not be delivered to B merely because B happens to be running. A mismatch requires waiting or scheduling the intended context, which is a separate operation. Equal interrupt numbers are not enough to establish identity across virtual contexts. Read the number, owning VM, and current execution context together before interpreting an acknowledge event.
An incorrect target of B can leave A waiting while B's state advances. Repeatedly unmasking A does not repair that ownership error. Correct the target only after identifying the request's owner, then verify that B's unrelated pending state, active state, and memory stay unchanged. A condition that merely requires some handler to run can accept an isolation failure as success. State both the changes required for progress and the state that must remain untouched during the experiment.
Inspect delivery as an explicit predicate
The calculation below separates the selected preconditions for acknowledgement. It assumes a request has already become pending and checks enable state, masking, recipient, and running VM. It is a predicate for this teaching configuration, not the full GIC architecture. The initial case fails because of masking; changing only that flag permits delivery. Switching the running context to B then blocks it again, showing that fixing masking has not bypassed ownership checks.
For diagnosis, also preserve the reason a gate rejected delivery. In a teaching model this identifies the blocked boundary; it is not a reason to disclose unrelated internal information. If several inputs are wrong, repairing one does not satisfy the entire contract. Test each gate independently and then test combinations. A passing normal example demonstrates one valid path. It does not establish that every invalid recipient or configuration is rejected, which requires separate counterexamples.
function eligible(s) {
return s.pending && s.enabled && !s.masked &&
s.target === s.running && !s.active;
}
const s = {pending:true, enabled:true, masked:true,
target:'A', running:'A', active:false};
const trace = [eligible(s)];
s.masked = false; trace.push(eligible(s));
s.running = 'B'; trace.push(eligible(s));
console.log(trace.join(','));
Injection, acknowledgement, and completion are not one operation
Injection in this model prepares a pending virtual request for the guest. It does not establish that the guest obtained an interrupt ID or finished the corresponding work. A normal trace separately records creation of pending state, eligibility, acknowledgement, source servicing, EOI, and deactivation. With EOImode fixed to one, priority drop and active-state clearing remain separate, and a persistent source can make work pending again after handling ends.
Hardware virtualization support can process guest interrupt-interface operations without entering an EL2 software handler each time. Consequently, do not read every model arrow as one mandatory trap. The arrows identify responsibility and state transitions, while the real access path depends on configuration. When advancing to an implementation, determine which accesses are intercepted and which are handled by architectural support. A correct conceptual delivery trace is useful evidence about the selected state machine, not a measured count of hypervisor entries.
| Stage | Established fact | Not yet established |
|---|---|---|
| Injection | Recipient request is pending | Handler already ran |
| Acknowledge | ID obtained; active handling | Source condition cleared |
| EOI | Priority handling ended | Active state cleared |
| Deactivate | Active state cleared | Persistent level disappeared |
Separate waiting for work from waiting for its notification
A waiting guest may have no completed data, or completed data may exist while its notification remains blocked. In block I/O, inspecting the used ring distinguishes those cases. Observing only interrupts can misdiagnose a masking problem as a stopped device. Polling is useful here as an independent observation of work completion, not as a universal replacement for interrupt handling. Receipt of an interrupt also does not prove that the completed request contains correct data or a successful status.
A useful boundary case switches VMs immediately after a request becomes pending. Save the non-running VM's state and verify that the same request remains when it returns. Generating a fresh request every time would hide a lost checkpoint. Keep A's request pending, run B without misdelivery, and return to A for acknowledgement. These three properties provide a stronger check than an animation that eventually moves, because the test preserves identity across the interval where ownership could be confused.
Exercise: repair a mask and an incorrect recipient
In the first repair task, target and running VM are A but the IRQ mask remains set. Permit acknowledgement without deleting pending work, service the source, and finish EOI and deactivation. In the second, a request belonging to A has an incorrect target of B. Advance only A's handling and leave B's unrelated state untouched. Explain the exact gate, owner, and transition repaired; saying only that interrupts were enabled does not identify the original defect.
For regression checks, vary the initial masking state and the position of a VM switch. Acceptance depends on computed state, not a match against one expected source string. Editing a previously passing configuration creates a currently unchecked input. The historical pass can remain recorded, but it must not be displayed as proof that the new input also passes. That distinction lets you experiment while retaining a precise account of which configuration actually delivered the request correctly.