STRUCT ACRN_IO_REQUEST(9)

💖 NAME 💖

struct acrn_io_request — the 256-byte ACRN I/O request, bestie. That's the whole vibe. ✨

This page lives in the Kernel API Manual, so like… that's the manual name, consider it folded in and acknowledged 🫶

---

🌸 SYNOPSIS 🌸

struct acrn_io_request {
    __u32 type;
    __u32 completion_polling;
    __u32 reserved0[14];
    union {
      struct acrn_pio_request         pio_request;
      struct acrn_pci_request         pci_request;
      struct acrn_mmio_request        mmio_request;
      __u64 data[8];
    } reqs;
    __u32 reserved1;
    __u32 kernel_handled;
    __u32 processed;
 };

---

🎀 Members 🎀

okay so let's meet the whole cast, no skips:

• type — what kind of request this even is (ACRN_IOREQ_TYPE_*). the main character identifier, iykyk 💅
• completion_polling — the polling flag, lowkey important: if it's set, the hypervisor will poll for the completion of the I/O request 👀
• reserved0 — reserved fields. not for you, bestie. hands off 🙈
• reqs — the union of all the different request types. byte offset: 64 🎯
  • reqs.pio_request — the PIO request data of the I/O request
  • reqs.pci_request — the PCI configuration space request data of the I/O request
  • reqs.mmio_request — the MMIO request data of the I/O request
  • reqs.data — the raw data of the I/O request (unfiltered, raw, iconic)
• reserved1 — reserved fields again. still not yours 🚫
• kernel_handled — a flag that says this request needs to be handled in the kernel, fr fr
• processed — the status of this request (ACRN_IOREQ_STATE_*) ⭐

---

🦋 Description 🦋

Here's the state transitions of the ACRN I/O request, and honestly? it's giving glow-up cycle:

FREE -> PENDING -> PROCESSING -> COMPLETE -> FREE -> ...

So when an I/O request is chilling in the COMPLETE or FREE state, it is owned by the hypervisor. HSM and ACRN userspace are in charge of processing all the others. that's the split, periodt 💜

On the basis of the states illustrated above, a typical lifecycle of an ACRN IO request would look like this — flow, assuming the initial state is FREE, with our cast of Service VM vCPU 0, Service VM vCPU x, and User vCPU y:

1. hypervisor — fills in type, addr, etc. Then pauses the User VM vCPU y, and sets the state to PENDING (a). Then fires an upcall to the Service VM 💫
2. HSM — scans for PENDING requests, sets the states to PROCESSING (b), and assigns the requests to clients (c) 🫶
3. client — scans for the assigned requests and handles the requests (d) 🔥
4. HSM — sets states to COMPLETE and notifies the hypervisor ⭐
5. hypervisor — resumes User VM vCPU y (e) 🌈
6. hypervisor — post handling (f), and sets states to FREE. full circle, back to the start 🎀

no cap, this part matters: the procedures (a) to (f) in the illustration above require to be strictly processed in the order. One vCPU cannot trigger another request of I/O emulation before completing the previous one. do not skip ahead, bestie, the order is the whole point 😭

Also, atomic and barriers are required when HSM and hypervisor accessing the state of struct acrn_io_request. that's not a suggestion, that's the rule 💀

---

👑 SEE ALSO 👑

Kernel file ./include/uapi/linux/acrn.h and the whole friend group:

struct acrn_mmio_request(9), struct acrn_pio_request(9), struct acrn_pci_request(9), struct acrn_ioreq_notify(9), struct acrn_vm_creation(9), struct acrn_gp_regs(9), struct acrn_descriptor_ptr(9), struct acrn_regs(9), struct acrn_vcpu_regs(9), struct acrn_vm_memmap(9), struct acrn_ptdev_irq(9), struct acrn_pcidev(9), struct acrn_mmio_dev_res(9), struct acrn_mmiodev(9), struct acrn_vdev(9), struct acrn_msi_entry(9), struct acrn_cstate_data(9), struct acrn_pstate_data(9), struct acrn_ioeventfd(9), struct acrn_irqfd(9)

---

that's the whole page, bestie, you ate it 💅✨

source: ./include/uapi/linux · version/date: October 2026 · and this whole thing is struct acrn_io_request(9) — go be iconic with your I/O requests 🎀🦋💖