kvm_gpc_refresh(9)

📦 version 7.3.1, in nixpkgs unstable

💖 kvm_gpc_refresh — kernel API manual, but make it make sense 💖

okay so bestie, welcome to the kvm_gpc_refresh(9) page — it lives in the kernel API manual and it's literally all about updating a cache you already initialized. no cap, that's the whole vibe.

✨ NAME ✨

kvm_gpc_refresh — update a previously initialized cache.

like, the cache already exists, you already set it up, and now you just want it fresh again. periodt. 💅

🦋 SYNOPSIS 🦋

int kvm_gpc_refresh (struct gfn_to_pfn_cache *gpc , unsigned long len );

there it is, character for character, wouldn't dream of touching it 🫶

🎀 ARGUMENTS 🎀

  • gpc — a struct gfn_to_pfn_cache object. yeah. that's the thing you're refreshing, bestie.
  • len — a sanity check 🧚 the range being accessed must fit inside a single page. that's the rule, and the function will absolutely hold you to it.

⭐ RETURN ⭐

  • 0 — success, slay 🎉
  • -EINVAL — you asked for a mapping that would cross a page boundary. nope, not today 💀
  • -EFAULT — the guest physical address is untranslatable. it's giving "can't even find it" 😭

🌸 DESCRIPTION 🌸

so this function will attempt to refresh a gfn_to_pfn_cache. sounds simple, right? but — and this is the part everyone skips — a successful return from this function does not mean the page can be immediately accessed, because it may have raced with an invalidation. literally a whole race condition situation 🙈

so what do callers do? they must still lock and check the cache status themselves. this function does not return with the lock still held to permit access — so don't go assuming you've got the lock and can just waltz in and read the page. you can't. lock, check, then access. in that order. iykyk 🔥

💜 lowkey the most important sentence on this page: a successful return does not mean the page can be immediately accessed. say it with me. it may have raced with an invalidation.

🌈 SEE ALSO 🌈

kernel file ./include/linux/kvm_host.h ✨ and all these iconic siblings:

and that's the whole page, bestie 💖 this one ships from ./include/linux, October 2026, and it's the kvm_gpc_refresh(9) page, so go forth, lock that cache, check that status, and stay hydrated 🍓🧚👑

📦 where this page comes from