get_update_locks_by_apqn(9)

💅 get_update_locks_by_apqn(9) — kernel API manual, bestie edition

okay so first things first, this is a page from the Kernel API Manual, section 9 (the kernel API section, iykyk), and the star of the show is get_update_locks_by_apqn. buckle up 🎀

---

✨ NAME ✨

get_update_locks_by_apqn — find the mdev that an APQN is assigned to, and grab all the locks you need before updating the APCB of the KVM guest that mdev is attached to. literally that's the whole job 🫶

---

🌸 SYNOPSIS 🌸

struct ap_matrix_mdev * get_update_locks_by_apqn (int apqn );

---

🦋 ARGUMENTS 🦋

• apqn — the APQN of a queue device. that's it, that's the argument 💅

---

👑 DESCRIPTION 👑

ok so the proper locking order — and yes, order matters, do not freestyle this — is:

1. matrix_dev->guests_lock: you need this one to use the KVM pointer and update a KVM guest's APCB.
2. matrix_mdev->kvm->lock: you need this one to update a guest's APCB.
3. matrix_dev->mdevs_lock: you need this one to access data stored in a matrix_mdev.

three locks, one very specific sequence, no cap 🔥

---

🙈 NOTE 🙈

careful bestie: if apqn is not assigned to a matrix_mdev, then matrix_mdev->kvm->lock will not be taken. so don't go assuming you're holding it — check first, fr fr 💀

---

⭐ RETURN ⭐

it gives you back the ap_matrix_mdev object that apqn is assigned to — or NULL if apqn isn't assigned to an ap_matrix_mdev at all. no object, no locks, no drama 🌈

---

💖 SEE ALSO 💖

the whole friend group 👇

• Kernel file ./drivers/s390/crypto/vfio_ap_ops.c
• 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_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)
• handle_pqap(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!! this lil icon came from ./drivers/s390/crypto (that's the source, bestie 🍓) and it's dated October 2026, filed under get_update_locks_by_apqn(9). go forth and lock in the right order, mwah 💋✨