OpenBSD manual page server

Manual Page Search Parameters

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

km_alloc, km_freekernel memory allocator

#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);

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

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

malloc(9), uvm_init(9)

December 6, 2019 OpenBSD-7.3