KM_ALLOC(9)

💖 NAME 💖

okay bestie, welcome to the km_alloc(9) page from the Kernel Developer’s Manual — it’s literally the kernel memory allocator vibe check.

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 💅

So km_alloc() allocates kernel virtual space that’s optionally backed by physical pages. And km_free() frees the space that was previously allocated by km_alloc(). iconic little duo, no cap 💫

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. Also important: the arguments passed to km_free() must match those that were used to obtain the space in km_alloc(). like, matching set, bestie 🎀

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.

✨ custom allocation modes ✨

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. that’s the whole mood 💀✨

---

🌈 SEE ALSO 🌈

• malloc(9)
• uvm_init(9)

---

xoxo, with love from Debian — December 6, 2019 💅✨