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:

For physical pages the predefined modes are:

The other parameters for allocation are:

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)