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

# NAME

`km_alloc`, `km_free` — kernel memory allocator

# SYNOPSIS

`#include <sys/types.h>`
`#include <uvm/uvm_extern.h>`

void *
`km_alloc`(size_t sz, const struct kmem_va_mode *kv, const struct kmem_pa_mode *kp, const struct kmem_dyn_mode *kd);

void
`km_free`(void *v, size_t sz, const struct kmem_va_mode *kv, const struct kmem_pa_mode *kp);

# DESCRIPTION

The `km_alloc`() function allocates kernel virtual space optionally backed by physical pages. The `km_free`() function frees the space that was previously allocated by `km_alloc`().

The sz argument specifies the size of the allocation and must be a multiple of `PAGE_SIZE`. The kv and kp arguments specify the type of virtual and physical memory to be allocated. The kd argument specifies additional options for the allocation. The arguments passed to `km_free`() must match those that were used to obtain the space in `km_alloc`().

Typically a user will use certain predefined modes for memory allocation. For virtual space the predefined modes are:

kv_any
  Allocates the virtual space anywhere.
kv_intrsafe
  Allocates the virtual space in the interrupt safe map.
kv_page
  Allocates single pages.

For physical pages the predefined modes are:

kp_dirty
  Maps dirty pages into the allocation.
kp_zero
  Maps zeroed pages into the allocation.
kp_dma
  Maps dma-accessible pages into the allocation.
kp_dma_zero
  Maps zeroed dma-accessible pages into the allocation.
kp_pageable
  Pages will be demand paged.
kp_none
  Leaves the allocation unmapped.

The other parameters for allocation are:

kd_waitok
  Sleeping for physical pages is allowed.
kd_nowait
  Sleeping is not allowed.
kd_trylock
  Fail if the allocator cannot obtain locks without waiting.

In case the predefined allocation modes are not sufficient, a custom allocation mode can be created. The structure controlling the virtual space allocation is:

    struct kmem_va_mode {
    	struct vm_map **kv_map;
    	vsize_t kv_align;
    	int kv_wait;
    	int kv_singlepage;
    };

kv_map
  A pointer to the pointer to the uvm_map the space will be allocated from.
kv_align
  Alignment constraint of the allocated space.
kv_wait
  A flag indicating whether the allocator should wait for space to be freed if the allocation cannot be satisfied.
kv_singlepage
  A flag indicating if the allocations will always be for single pages.

    struct kmem_pa_mode {
    	struct uvm_constraint_range *kp_constraint;
    	struct uvm_object **kp_object;
    	paddr_t kp_align;
    	paddr_t kp_boundary;
    	int kp_nomem;
    	int kp_maxseg;
    	int kp_zero;
    	int kp_pageable;
    };

kp_constraint
  A pointer to physical allocation constraints.
kp_object
  A pointer to a pointer to a uvm_object if the pages should be backed by a kernel object.
kp_align
  Physical alignment of the first page in the allocation.
kp_boundary
  Boundary that the physical addresses can't cross if the allocation is contiguous.
kp_nomem
  A flag that specifies that the allocation should not be backed by physical pages.
kp_maxseg
  Maximal amount of contiguous physical segments in the allocation.
kp_zero
  A flag that specifies if the returned memory should be zeroed.
kp_pageable
  A flag that specifies if the returned memory should be demand paged from the backing object instead of being allocated up front.

    struct kmem_dyn_mode {
    	int kd_waitok;
    	int kd_trylock;
    	voff_t kd_prefer;
    	int *kd_slowdown;
    };

kd_waitok
  A flag that specifies if the allocator may sleep waiting for memory.
kd_trylock
  A flag that specifies if the allocator should fail if it can't immediately obtain a lock.
kd_prefer
  An offset given to PMAP_PREFER to virtually align the allocated space.
kd_slowdown
  A pointer to an integer that will be set to 1 if the internal single page allocator needs the caller to back off to allow the allocator to catch up.

# RETURN VALUES

`km_alloc`() returns a kernel virtual address or `NULL` if the allocation cannot be satisfied.

# SEE ALSO

malloc(9), uvm_init(9)

December 6, 2019 | Debian