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.