UVM_MAP(9) | Kernel Developer's Manual | UVM_MAP(9)

# 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

The UVM facility for virtual address space management.

# FUNCTIONS

`uvm_map`() establishes a valid mapping in 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:

- When uobj is `NULL` and uoffset is `UVM_UNKNOWN_OFFSET`, `uvm_map`() does not use the machine-dependent `PMAP_PREFER` function.
- When uobj is `NULL` and uoffset is any other value, it is used as the hint to `PMAP_PREFER`.
- When uobj is not `NULL` and uoffset is `UVM_UNKNOWN_OFFSET`, `uvm_map`() finds the offset based upon the virtual address, passed as startp.
- 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.

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 to extraction 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 entires in the range for this mapping should be unmapped as part of creating the new mapping. Use of this flag without also specifying `UVM_FLAG_FIXED` is a bug.

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`() removes a valid mapping, from start to end, in map map, which must be unlocked.

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

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

`uvm_map_protect`() changes the protection start to end in 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`() verifies that the new permissions honor PAX restrictions if applicable and forwards to `uvm_map_protect`() on passing.

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

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

`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`() 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`() lowers the reference count on the address space vm, freeing the data structures if there are no other references.

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

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

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

`uvm_uarea_system_alloc`() and `uvm_uarea_system_free`() are optimized routines, which are used for kernel threads.

# SEE ALSO

pmap(9), uvm(9), uvm_km(9), vmem(9)

# HISTORY

UVM and `uvm_map` first appeared in NetBSD 1.4.

May 20, 2017 | NetBSD 9.5