VM_MAP_FIND(9)

💖 VM_MAP_FIND 💖

okay bestie, gather round, because we're diving into the Kernel Developer's Manual and today's main character is vm_map_find(9) — she finds free regions in a map and (if she's feeling generous) maps a vm_object for you too. no cap. 🦋

---

✨ NAME ✨

vm_map_find — find a free region within a map, and optionally map a vm_object

---

🌸 SYNOPSIS 🌸

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

int
vm_map_find(vm_map_t map, vm_object_t object, vm_ooffset_t offset,
    vm_offset_t *addr, vm_size_t length, vm_offset_t max_addr,
    int find_space, vm_prot_t prot, vm_prot_t max, int cow);

---

🎀 DESCRIPTION 🎀

So basically, vm_map_find() rolls up to the target map and tries to find a free region in it that's the given length. And if she finds one? She literally creates a mapping of object by calling vm_map_insert(9). it's giving matchmaker energy fr fr 💅

The arguments offset, prot, max, and cow get passed unchanged to vm_map_insert(9) when creating the mapping — but only if and only if a free region was found. no free region, no mapping, no passing. periodt.

If object is non-NULL, the reference count on that object must be incremented by the caller before calling this function, to account for the new entry. do not skip this step bestie, I'm begging 😭

If max_addr is non-zero, it specifies an upper bound on the mapping. The mapping will only succeed if a free region can be found that resides entirely below max_addr. it's giving ceiling, not a suggestion.

The find_space argument is the vibe check — it tells the function which strategy to use when searching for a free region of the requested length. For all values other than VMFS_NO_SPACE, vm_map_findspace(9) gets called to locate a free region of the requested length with a starting address at or above *addr. here are the strategies, and yes, there's lore:

• VMFS_NO_SPACE — The mapping will only succeed if there is a free region of the requested length at the given address *addr. she's picky, she knows what she wants 💅
• VMFS_ANY_SPACE — The mapping will succeed as long as there is a free region. lowkey the chill one, she's not fussy 🌈
• VMFS_SUPER_SPACE — The mapping will succeed as long as there is a free region that begins on a superpage boundary. But if object is non-NULL and is already backed by superpages, then the mapping will require a free region that aligns relative to the existing superpages rather than one beginning on a superpage boundary. she's flexible but only in the specific way she's flexible 😌
• VMFS_OPTIMAL_SPACE — The mapping will succeed as long as there is a free region. However, if object is non-NULL and is already backed by superpages, this strategy will attempt to find a free region aligned relative to the existing superpages. she's trying her best and honestly it's working ✨
• VMFS_ALIGNED_SPACE(n) — The mapping will succeed as long as there is a free region that aligns on a 2^n boundary. math girlie behavior, we love to see it 🧮

---

👑 IMPLEMENTATION NOTES 👑

This function acquires a lock on map by calling vm_map_lock(9), and holds it until the function returns. she does not let go early, do not test her 🔒

The search for a free region is defined to be first-fit, from the address addr onwards. first come, first served, no cutting the line.

---

🔥 RETURN VALUES 🔥

vm_map_find() returns KERN_SUCCESS if the mapping was successfully created. slay 💖

If space could not be found, or if find_space was VMFS_NO_SPACE and the given address addr was already mapped, KERN_NO_SPACE will be returned.

If the discovered range turned out to be bogus, KERN_INVALID_ADDRESS will be returned. not her fault, the range was lying to her 💀

---

🌟 SEE ALSO 🌟

vm_map(9), vm_map_findspace(9), vm_map_insert(9), vm_map_lock(9)

the whole friend group, honestly. go read all of them, iykyk 🫶

---

💜 AUTHORS 💜

This manual page was written by Bruce M Simpson <bms@spc.org>. king behavior, we stan 👑

---

and that's the whole page bestie! written for Debian, dated September 12, 2013, living under the VM_MAP_FIND(9) header. go forth and map responsibly 💅✨🎀🦋