write_guest_with_key(9)

📦 version 7.3.1, in nixpkgs unstable

💫 write_guest_with_key(9) — a Kernel API Manual moment ✨

okay bestie, buckle up, because this one is from the Kernel API Manual and it's lowkey iconic: it's all about yeeting bytes from kernel space into guest space 🎀

✨ NAME ✨

write_guest_with_key — copy data from kernel space to guest space 🫶

🌸 SYNOPSIS 🌸

int write_guest_with_key (struct kvm_vcpu *vcpu , unsigned long ga , u8
ar , void *data , unsigned long len , u8 access_key );

🦋 ARGUMENTS 🦋

  • vcpu — the virtual cpu, the main character of this whole situation 💅
  • ga — the guest address, i.e. where the data is headed
  • ar — the access register
  • data — the source address, and it lives in kernel space
  • len — how many bytes we're copying, no cap
  • access_key — the access key that the storage key needs to match 🔑

💖 DESCRIPTION 💖

So what it does is: copy len bytes from data (kernel space) over to ga (guest address). Easy enough, right? But the way it actually gets there is kind of a whole investigation 👑

To copy data into guest space, the PSW of the vcpu gets inspected, fr fr:

  • if DAT is off, the data gets copied to guest real or absolute memory
  • if DAT is on, the data gets copied to the address space as specified by the address space bits of the PSW: Primary, secondary, home space, or access register mode

The addressing mode of the PSW gets inspected too, so that address wrap around is taken into account for 24-, 31- and 64-bit addressing mode — this matters if the to-be-copied data crosses page boundaries in guest address space. And before copying any data at all, it performs low address, DAT and key protection checks. like, it does its homework first, we love a prepared queen 🌸

Also, hear me out: this function modifies the 'struct kvm_s390_pgm_info pgm' member of vcpu. If there's an access exception (e.g. a protection exception), pgm will contain all the data necessary so that a subsequent call to 'kvm_s390_inject_prog_vcpu' will inject a correct exception into the guest. But if no access exception happened, the contents of pgm are undefined when this function returns 😭 so don't go reading them, bestie.

🔥 RETURN 🔥

  • zero on success ✨
  • a negative value if e.g. the guest mapping is broken, or in case of out-of-memory. In this case the contents of pgm are undefined. Also, parts of data may have been copied to guest space 👀
  • a positive value if an access exception happened. In this case the returned value is the program interruption code, and the contents of pgm may be used to inject an exception into the guest. No data has been copied to guest space. periodt 💅

💀 NOTE 💀

in case an access exception is recognized, no data has been copied to guest space — and yes, that's also true if the to-be-copied data would cross one or more page boundaries in guest space. So this function may be used for nullifying and suppressing instruction emulation. It may also be used for terminating instructions, if it is undefined whether data has been changed in guest space in case of an exception. like… that's the fine print, don't skip it 🙈

🌈 SEE ALSO 🌈

Kernel file ./arch/s390/kvm/s390/gaccess.h and all these gorgeous neighbours:

okay that's the whole page, mwah 💋 this one lives in ./arch/s390/kvm/s390 and it's dated October 2026 — screenshot it, cite it, slay it 🧚‍♀️💜

📦 where this page comes from