te
Copyright 2014 Nexenta Systems, Inc. All rights reserved.
Copyright 2022 Joyent, Inc.
Copyright 1989 AT&T
Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved
The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
kmem_alloc, kmem_zalloc, kmem_free - allocate kernel memory

#include <sys/types.h>
#include <sys/kmem.h>



void *kmem_alloc(size_t size, int flag);

void *kmem_zalloc(size_t size, int flag);

void kmem_free(void *buf, size_t size);

Architecture independent level 1 (DDI/DKI). size flag buf The kmem_alloc() function allocates size bytes of kernel memory and returns a pointer to the allocated memory. The allocated memory is at least double-word aligned, so it can hold any C data structure. No greater alignment can be assumed. flag determines whether the caller can sleep for memory. KM_SLEEP allocations may sleep but are guaranteed to succeed. KM_NOSLEEP and KM_NOSLEEP_LAZY allocations are guaranteed not to sleep but may fail (return NULL) if no memory is currently available. KM_NOSLEEP will first attempt to aggressively reclaim memory from otherwise unused blocks, while KM_NOSLEEP_LAZY will not attempt any reclamation. The initial contents of memory allocated using kmem_alloc() are random garbage.

The kmem_zalloc() function is like kmem_alloc() but returns zero-filled memory.

The kmem_free() function frees previously allocated kernel memory. The buffer address and size must exactly match the original allocation. Memory cannot be returned piecemeal.

If successful, kmem_alloc() and kmem_zalloc() return a pointer to the allocated memory. If KM_NOSLEEP is set and memory cannot be allocated without sleeping, kmem_alloc() and kmem_zalloc() return NULL. The kmem_alloc() and kmem_zalloc() functions can be called from interrupt context only if the KM_NOSLEEP flag is set. They can be called from user context with any valid flag. The kmem_free() function can be called from from user, interrupt, or kernel context. copyout (9F), freerbuf (9F), getrbuf (9F)

Writing Device Drivers

Memory allocated using kmem_alloc() is not paged. Available memory is therefore limited by the total physical memory on the system. It is also limited by the available kernel virtual address space, which is often the more restrictive constraint on large-memory configurations.

Excessive use of kernel memory is likely to affect overall system performance. Overcommitment of kernel memory will cause the system to hang or panic.

Misuse of the kernel memory allocator, such as writing past the end of a buffer, using a buffer after freeing it, freeing a buffer twice, or freeing a null or invalid pointer, will corrupt the kernel heap and may cause the system to corrupt data or panic.

The initial contents of memory allocated using kmem_alloc() are random garbage. This random garbage may include secure kernel data. Therefore, uninitialized kernel memory should be handled carefully. For example, never copyout(9F) a potentially uninitialized buffer.

kmem_alloc(0, flag) always returns NULL, but if KM_SLEEP is set, this behavior is considered to be deprecated; the system may be configured to explicitly panic in this case in lieu of returning NULL. kmem_free(NULL, 0) is legal, however.