VM_MAP_SUBMAP(9)

💫 VM_MAP_SUBMAP 💫

okay bestie, welcome to section 9 of the Kernel Developer's Manual — we're deep in kernel land today and honestly? it's giving wizard energy 🧙‍♀️✨

🌸 NAME 🌸

vm_map_submap — create a subordinate map (yes, a whole baby map inside your map, we love a nested situation 🎀)

✨ SYNOPSIS ✨

#include <sys/param.h>
#include <vm/vm.h>
#include <vm/vm_map.h>

int
vm_map_submap(vm_map_t map, vm_offset_t start, vm_offset_t end,
    vm_map_t submap);

💜 DESCRIPTION 💜

so here's the tea, bestie: vm_map_submap() takes the range that's bounded by start and end inside the map map, and marks it as being handled by a subordinate map called sub_map. literally handing off a chunk of your map to a smaller map like "here girl, you take this one" 🫶

and who's out here calling this? mostly the kernel memory allocator, no cap. it's their little helper function.

🧚 IMPLEMENTATION NOTES 🧚

⚠️ okay this part is important, don't skip it

• this function is for internal use only. like, it's not a public-facing slay, it's an internal-use-only slay 🙈
• both maps must exist. you can't just vibe with a nonexistent map, that's not the move.
• the range must have been created with vm_map_find(9) beforehand. prior setup is mandatory, periodt.
• no other operations may have been performed on this range before you call this function. none. zero. clean slate only 💅
• after you call this function, only the vm_fault() operation may be performed within this range. that's the one and only thing allowed in there afterward, iykyk.
• wanna remove a submapping? okay so: first you have to remove the range from the parent map, and then destroy the sub_map. that's the order, no shortcuts.
• > 🚨 and just so we're clear: this removal procedure is not recommended. like, the manpage literally says don't. so… don't. 😭

🌈 RETURN VALUES 🌈

• KERN_SUCCESS — returned if it worked! iconic, no notes 💖
• KERN_INVALID_ARGUMENT — returned otherwise, and here's when:
  • the caller requested copy-on-write flags 🙈
  • the range you specified for the sub-map was out of range for the parent map 💀
  • a NULL backing object was specified 🍓

🔥 SEE ALSO 🔥

• vm_map(9)
• vm_map_find(9)

👑 AUTHORS 👑

this manual page was written by Bruce M Simpson <bms@spc.org>. ty bestie for the docs, we appreciate you fr fr 💜

and that's the whole page, bestie! this one's from the Debian crew and it's dated July 19, 2003 — a vintage classic, honestly, and it still ate 🌸✨💅