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_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.

Note that uvm_map() does not add a reference to uobj; it is the caller's responsibility to do so.

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().

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_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.