guest_range_to_gpas(9)

📦 version 7.3.1, in nixpkgs unstable

💅 guest_range_to_gpas(9) — a Kernel API Manual moment

okay bestie, so we're in the guest_range_to_gpas(9) manpage, and honestly? this one's giving "s390 virtualization main character energy" and you're gonna slay it. ✨

🌸 NAME 🌸

guest_range_to_gpas — literally calculates the guest physical addresses of page fragments that cover a logical range. no cap, that's the whole gig. 💖

🦋 SYNOPSIS 🦋

int guest_range_to_gpas (struct kvm_vcpu *vcpu , unsigned long ga , u8
ar , unsigned long *gpas , unsigned long len , const union asce asce ,
enum gacc_mode mode , u8 access_key );

like, yes, it's a long signature. it ate, honestly. 🎀

✨ ARGUMENTS ✨

  • vcpu — the virtual cpu, our protagonist 💫
  • ga — guest address, aka where the range starts
  • ar — access register, periodt
  • gpas — output argument, and heads up: it may be NULL 🙈
  • len — length of the range, measured in bytes
  • asce — address-space-control element to use for translation (say that five times fast, i dare you)
  • mode — access mode, obviously
  • access_key — access key to mach the range's storage keys against 🗝️ (yes, "mach", that's what it says, i don't make the rules)

🔥 DESCRIPTION 🔥

So basically: this bad boy translates a logical range into a series of guest absolute addresses, such that the concatenation of page fragments starting at each gpa make up the whole range. it's giving "assemble the range from page-fragment pieces" and honestly, iconic. 🧩

The translation is performed as if done by the cpu for the given asce, ar, mode and state of the vcpu. so like, it's cosplaying the cpu's whole translation vibe. 👑

If the translation causes an exception, its program interruption code is returned and the struct kvm_s390_pgm_info pgm member of vcpu is modified such that a subsequent call to kvm_s390_inject_prog_vcpu will inject a correct exception into the guest. yes bestie, it sets up the exception for you. thoughtful. 🫶

The resulting gpas are stored into gpas, unless it is NULL. simple as. 💅

📌 NOTE 📌

All fragments except the first one start at the beginning of a page. and when deriving the boundaries of a fragment from a gpa, all but the last fragment end at the end of the page. so like, first one's special, last one's special, the middle ones are just living their page-aligned truth. 🌈

⭐ RETURN ⭐

  • 0 — success, we love to see it 🎉
  • <0 — translation could not be performed, for example if guest memory could not be accessed 😭
  • >0 — an access exception occurred. 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 💀

👑 SEE ALSO 👑

Kernel file ./arch/s390/kvm/s390/gaccess.c, plus these absolute legends:

go read them, iykyk 📚💜

and that's the page, bestie!! 🫶 this little gem lives under ./arch/s390/kvm/s390 in the Kernel API Manual, and it's dated October 2026. so futuristic of it. 💫 now go forth and translate those ranges — you're gonna do amazing, fr fr. 🌸🎀💖

📦 where this page comes from