handle_pqap(9)

💅 handle_pqap — the PQAP instruction callback 🎀

okay so bestie, this is handle_pqap, straight out of the Kernel API Manual, and it's literally the function that catches a PQAP instruction and decides whether KVM is gonna deal with it or hand it off to QEMU. it's giving gatekeeper energy, and honestly? iconic. ✨

---

🌸 SYNOPSIS 🌸

int handle_pqap (struct kvm_vcpu *vcpu );

like, that's the whole signature. yes the space before the ) is real, don't come for me, I'm just the messenger 🫶

---

🦋 ARGUMENTS 🦋

• vcpu — the vcpu that we received the PQAP instruction on. that's the one, that's the main character 👑

---

✨ DESCRIPTION ✨

first thing we do is grab the general register contents so we can initialize the internal variables. the registers are laid out like this, no cap:

• REG[0]: APQN
• REG[1]: IR and ISC
• REG[2]: NIB

then, Response.status may be set to one of these Response Codes:

• AP_RESPONSE_Q_NOT_AVAIL — if the queue is not available 🙈
• AP_RESPONSE_DECONFIGURED — if the queue is not configured 😭
• AP_RESPONSE_NORMAL (0) — in case of success 💖

heads up: check vfio_ap_setirq and vfio_ap_clrirq for other possible RC. and yeah, we take the matrix_dev lock to ensure serialization on queues and mediated device access — it's the vibe check that keeps everything from falling apart fr fr 🔥

---

🌈 RETURN 🌈

• 0 — if we could handle the request inside KVM. slay, done in-house 💅
• -EOPNOTSUPP — otherwise, returned so that QEMU can handle the fault. not our problem anymore, passed off with love 🫶

---

👑 SEE ALSO 👑

the kernel file itself, for the brave: ./drivers/s390/crypto/vfio_ap_ops.c

and like, the entire extended universe of friends, in the order they appear:

• get_update_locks_for_kvm(9)
• release_update_locks_for_kvm(9)
• get_update_locks_for_mdev(9)
• release_update_locks_for_mdev(9)
• get_update_locks_by_apqn(9)
• get_update_locks_for_queue(9)
• vfio_ap_mdev_get_queue(9)
• vfio_ap_wait_for_irqclear(9)
• vfio_ap_free_aqic_resources(9)
• vfio_ap_irq_disable(9)
• vfio_ap_validate_nib(9)
• ensure_nib_shared(9)
• vfio_ap_irq_enable(9)
• vfio_ap_le_guid_to_be_uuid(9)
• vfio_ap_mdev_verify_no_sharing(9)
• vfio_ap_mdev_validate_masks(9)
• assign_adapter_store(9)
• vfio_ap_mdev_unlink_adapter(9)
• unassign_adapter_store(9)
• assign_domain_store(9)
• unassign_domain_store(9)
• assign_control_domain_store(9)
• unassign_control_domain_store(9)
• vfio_ap_mdev_set_kvm(9)
• vfio_ap_mdev_unset_kvm(9)
• vfio_ap_mdev_resource_in_use(9)
• vfio_ap_mdev_hot_unplug_cfg(9)
• vfio_ap_mdev_cfg_remove(9)
• vfio_ap_mdev_on_cfg_remove(9)
• vfio_ap_filter_apid_by_qtype(9)
• vfio_ap_mdev_cfg_add(9)
• vfio_ap_mdev_on_cfg_add(9)
• vfio_ap_on_cfg_changed(9)

---

and that's the page, bestie 🧚 this little gem lives in the ./drivers/s390/crypto section of the Kernel API Manual and it's dated October 2026 — mark your calendars, screenshot it, send it to the group chat 💜