UVM_MAP(9)

📦
version 11.0 · 2 versions
, in nixpkgs unstable

🎀 UVM_MAP(9) 🎀

okay so bestie, this is the Kernel Developer's Manual page for uvm_map, and it is literally the virtual address space management interface. UVM is the whole facility here, and this page is its little group chat for mapping, unmapping, protecting, and managing address spaces. 💅

🌸 NAME 🌸

uvm_map — virtual address space management interface

✨ SYNOPSIS ✨

       #include <sys/param.h>
       #include <uvm/uvm.h>

       int
       uvm_map(struct vm_map *map, vaddr_t *startp, vsize_t size,
           struct uvm_object *uobj, voff_t uoffset, vsize_t align,
           uvm_flag_t flags);

       void
       uvm_unmap(struct vm_map *map, vaddr_t start, vaddr_t end);

       int
       uvm_map_pageable(struct vm_map *map, vaddr_t start, vaddr_t end,
           bool new_pageable, int lockflags);

       bool
       uvm_map_checkprot(struct vm_map *map, vaddr_t start, vaddr_t end,
           vm_prot_t protection);

       int
       uvm_map_protect(struct vm_map *map, vaddr_t start, vaddr_t end,
           vm_prot_t new_prot, bool set_max);

       int
       uvm_map_protect_user(struct lwp *l, vaddr_t start, vaddr_t end,
           vm_prot_t new_prot);

       int
       uvm_deallocate(struct vm_map *map, vaddr_t start, vsize_t size);

       struct vmspace *
       uvmspace_alloc(vaddr_t min, vaddr_t max);

       void
       uvmspace_exec(struct lwp *l, vaddr_t start, vaddr_t end);

       struct vmspace *
       uvmspace_fork(struct vmspace *vm);

       void
       uvmspace_free(struct vmspace *vm);

       void
       uvmspace_share(struct proc *p1, struct proc *p2);

       vaddr_t
       uvm_uarea_alloc(void);

       void
       uvm_uarea_free(vaddr_t uaddr);

       vaddr_t
       uvm_uarea_system_alloc(void);

       void
       uvm_uarea_system_free(vaddr_t uaddr);

💖 DESCRIPTION 💖

bestie, UVM is the facility for virtual address space management. That's the vibe: address-space admin, no cap. ✨

🫶 FUNCTIONS 🫶

okay so here's the function-by-function rundown, and yes, we are keeping every single detail because that's the whole point. 🔥

🌟 uvm_map()

uvm_map() establishes a valid mapping in the map map, which must be unlocked. The new mapping has size size, which must be a multiple of PAGE_SIZE. 🎀

The uobj and uoffset arguments can have four meanings:

  1. When uobj is NULL and uoffset is UVM_UNKNOWN_OFFSET, uvm_map() does not use the machine-dependent PMAP_PREFER function.
  2. When uobj is NULL and uoffset is any other value, it is used as the hint to PMAP_PREFER.
  3. When uobj is not NULL and uoffset is UVM_UNKNOWN_OFFSET, uvm_map() finds the offset based upon the virtual address, passed as startp.
  4. When uobj is not NULL and uoffset is any other value, then a regular mapping is performed at this offset. The start address of the map will be returned in startp.

If uobj is supplied, then uvm_map() consumes the caller's reference to uobj on success; uvm_unmap() will release it when removing this mapping. On failure, uvm_map() leaves the reference count of uobj unmodified. fr fr, that reference-count detail matters. 🫶

align specifies alignment of mapping unless UVM_FLAG_FIXED is specified in flags. align must be a power of 2.

flags passed to uvm_map() are typically created using the UVM_MAPFLAG(vm_prot_t prot, vm_prot_t maxprot, vm_inherit_t inh, int advice, int flags) macro, which uses the following values.

The values that prot and maxprot can take are:

  • UVM_PROT_NONE — no protection bits.
  • UVM_PROT_R — read.
  • UVM_PROT_W — write.
  • UVM_PROT_X — exec.
  • UVM_PROT_MASK — mask for extracting the protection bits.

Additionally, the following constants for ORed values are available: UVM_PROT_RW, UVM_PROT_RX, UVM_PROT_WX and UVM_PROT_RWX.

The values that inh can take are:

  • UVM_INH_SHARE — share the map.
  • UVM_INH_COPY — copy the map.
  • UVM_INH_NONE — no inheritance.
  • UVM_INH_MASK — mask to extract inherit flags.

The values that advice can take are:

  • UVM_ADV_NORMAL — "Normal" use.
  • UVM_ADV_RANDOM — "Random" access likelihood.
  • UVM_ADV_SEQUENTIAL — "Sequential" access likelihood.
  • UVM_ADV_MASK — mask to extract the advice flags.

The values that flags can take are:

  • UVM_FLAG_FIXED — attempt to map on the address specified by startp. Otherwise, it is used just as a hint.
  • UVM_FLAG_OVERLAY — establish overlay.
  • UVM_FLAG_NOMERGE — do not merge map entries, if such merge is possible.
  • UVM_FLAG_COPYONW — use copy-on-write, i.e. do not fault in the pages immediately.
  • UVM_FLAG_AMAPPAD — used for BSS: allocate larger amap, if extending is likely.
  • UVM_FLAG_TRYLOCK — fail if cannot acquire the lock immediately.
  • UVM_FLAG_NOWAIT — not allowed to sleep. Fail, in such case.
  • UVM_FLAG_QUANTUM — indicates that map entry cannot be split once mapped.
  • UVM_FLAG_WAITVA — sleep until VA space is available, if it is not.
  • UVM_FLAG_VAONLY — unmap only VA space. Used by uvm_unmap().
  • UVM_FLAG_UNMAP — any existing entries in the range for this mapping should be unmapped as part of creating the new mapping.
⚠️ bestie, heads up: use of UVM_FLAG_UNMAP without also specifying UVM_FLAG_FIXED is a bug. not a cute look 💀

The UVM_MAPFLAG macro arguments can be combined with an or operator. There are several special purpose macros for checking protection combinations, e.g., the UVM_PROT_WX. There are also some additional macros to extract bits from the flags. The UVM_PROTECTION, UVM_INHERIT, UVM_MAXPROTECTION and UVM_ADVICE macros return the protection, inheritance, maximum protection, and advice, respectively. uvm_map() returns zero on success or error number otherwise.

🧚 uvm_unmap()

uvm_unmap() removes a valid mapping, from start to end, in the map map, which must be unlocked.

🦋 uvm_map_pageable()

uvm_map_pageable() changes the pageability of the pages in the range from start to end in the map map to new_pageable. uvm_map_pageable() returns zero on success or error number otherwise.

🌸 uvm_map_checkprot()

uvm_map_checkprot() checks the protection of the range from start to end in the map map against protection. This returns either true or false. ✨

💜 uvm_map_protect()

uvm_map_protect() changes the protection of the range from start to end in the map map to new_prot, also setting the maximum protection to the region to new_prot if set_max is true. This function returns a standard UVM return value.

🌈 uvm_map_protect_user()

uvm_map_protect_user() verifies that the new permissions honor PAX restrictions if applicable and forwards to uvm_map_protect() on passing. slay, permission-checked 💅

🍓 uvm_deallocate()

uvm_deallocate() deallocates kernel memory in the map map from address start to start + size.

👑 uvmspace_alloc()

uvmspace_alloc() allocates and returns a new address space, with ranges from min to max.

🎀 uvmspace_exec()

uvmspace_exec() either reuses the address space of thread l (its process) if there are no other references to it, or creates a new one with uvmspace_alloc(). The range of valid addresses in the address space is reset to start through end.

🦋 uvmspace_fork()

uvmspace_fork() creates and returns a new address space based upon the vm address space, typically used when allocating an address space for a child process.

🌟 uvmspace_free()

uvmspace_free() lowers the reference count on the address space vm, freeing the data structures if there are no other references.

💖 uvmspace_share()

uvmspace_share() causes process p2 to share the address space of p1.

🧚 uvm_uarea_alloc()

uvm_uarea_alloc() allocates memory for a u-area (i.e. kernel stack, PCB, etc) and returns the address.

🌸 uvm_uarea_free()

uvm_uarea_free() frees a u-area allocated with uvm_uarea_alloc().

🌈 uvm_uarea_system_alloc() and uvm_uarea_system_free()

uvm_uarea_system_alloc() and uvm_uarea_system_free() are optimized routines, which are used for kernel threads. main character energy for kernel threads only 👑

🔥 SEE ALSO 🔥

go read these too, bestie, iykyk 🫶

🌈 HISTORY 🌈

UVM and uvm_map first appeared in NetBSD 1.4.

This page's source/version is Debian, dated May 20, 2017, and the manual page is UVM_MAP(9) — okay bye bestie, hydrate and map safely 💖💅

📦 where this page comes from