Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.


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.

NetBSD 10.99                    August 15, 2015                   NetBSD 10.99