UVM_KM(9)

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

# NAME

`uvm_km` —
raw kernel memory or address space allocator

# SYNOPSIS

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

vaddr_t
`uvm_km_alloc`(struct vm_map *map, vsize_t size, vsize_t align, uvm_flag_t flags);

void
`uvm_km_free`(struct vm_map *map, vaddr_t addr, vsize_t size, uvm_flag_t flags);

struct vm_map *
`uvm_km_suballoc`(struct vm_map *map, vaddr_t *min, vaddr_t *max, vsize_t size, int flags, bool fixed, struct vm_map *submap);

# DESCRIPTION

The UVM facility for allocation of kernel memory or address space in pages. Both wired and pageable memory can be allocated by this facility, as well as kernel address space. Note that this is a raw allocator. For general purpose memory allocation, kmem(9) interface should be used.

# FUNCTIONS

`uvm_km_alloc`() allocates a contiguous range of size bytes of kernel memory in map map and returns the virtual address of the range, or returns zero on failure. The first address of the allocated memory range will be aligned according to the align argument (specify 0 if no alignment is necessary). The alignment must be a multiple of page size. The flags is a bitwise inclusive OR of the allocation type and operation flags.

The allocation type should be one of:

UVM_KMF_WIRED
  Wired memory.
UVM_KMF_PAGEABLE
  Demand-paged zero-filled memory.
UVM_KMF_VAONLY
  Virtual address only. No physical pages are mapped in the allocated region. If necessary, it is the caller's responsibility to enter page mappings. It is also the caller's responsibility to clean up the mappings before freeing the address range.

The following operation flags are available:

UVM_KMF_CANFAIL
  Can fail even if `UVM_KMF_NOWAIT` is not specified and `UVM_KMF_WAITVA` is specified.
UVM_KMF_ZERO
  Request zero-filled memory. Only supported for `UVM_KMF_WIRED`. Should not be used with other types.
UVM_KMF_EXEC
  Request memory with executable rights.
UVM_KMF_TRYLOCK
  Fail if cannot lock the map without sleeping.
UVM_KMF_NOWAIT
  Fail immediately if no memory is available.
UVM_KMF_WAITVA
  Sleep to wait for the virtual address resources if needed.

If neither `UVM_KMF_NOWAIT` nor `UVM_KMF_CANFAIL` are specified and `UVM_KMF_WAITVA` is specified, `uvm_km_alloc`() will never fail, but rather sleep indefinitely until the allocation succeeds.

Pageability of the pages allocated with `UVM_KMF_PAGEABLE` can be changed by `uvm_map_pageable`(). In that case, the entire range must be changed atomically. Changing a part of the range is not supported.

`uvm_km_free`() frees the memory range allocated by `uvm_km_alloc`(). addr must be an address returned by `uvm_km_alloc`(). map and size must be the same as the ones used for the corresponding `uvm_km_alloc`(). flags must be the allocation type used for the corresponding `uvm_km_alloc`(). Note that `uvm_km_free`() is the only way to free memory ranges allocated by `uvm_km_alloc`(). `uvm_unmap`() must not be used.

`uvm_km_suballoc`() allocates submap from map, creating a new map if submap is `NULL`. The addresses of the submap can be specified explicitly by setting the fixed argument to true, which causes the min argument to specify the beginning of the address in the submap. If fixed is false, any address of size size will be allocated from map and the start and end addresses returned in min and max. The flags are used to initialize the created submap. The following flags can be set:

VM_MAP_PAGEABLE
  Entries in the map may be paged out.
VM_MAP_INTRSAFE
  Map should be interrupt-safe.
VM_MAP_TOPDOWN
  A top-down mapping should be arranged.

# SEE ALSO

kmem(9), pmap(9), pool_cache(9), uvm(9), uvm_map(9), vmem(9)

# HISTORY

UVM and `uvm_km` first appeared in NetBSD 1.4.

August 15, 2015 | NetBSD 9.5