xmalloc Kernel Service

Purpose

Allocates memory.

Syntax

#include <sys/types.h>
#include <sys/errno.h>
#include <sys/malloc.h>

Parameters

Description

The xmalloc kernel service allocates an area of memory out of the heap specified by the heap parameter. This area is the number of bytes in length specified by the size parameter and is aligned on the byte boundary specified by the align parameter. The align parameter is actually the log base 2 of the desired address boundary. For example, an align value of 4 requests that the allocated area be aligned on a 2^4 (16) byte boundary.

There are multiple heaps provided by the kernel for use by kernel extensions. Two primary kernel heaps are kernel_heap and pinned_heap. Kernel extensions should use the kernel_heap value when allocating memory that is not pinned, and should use the pinned_heap value when allocating memory that should always be pinned or pinned for long periods of time. When allocating from the pinned_heap heap, the xmalloc kernel service will pin the memory before a successful return. The pin and unpin kernel services should be used to pin and unpin memory from the kernel_heap heap when the memory should only be pinned for a limited amount of time. Memory from the kernel_heap heap must be unpinned before freeing it. Memory from the pinned_heap heap should not be unpinned.

The kernel_heap heap points to one of the following heaps: kernel_heap_4K_64K and kernel_heap_16M. The pinned_heap heap points to one of the following heaps: pinned_heap_4K_64K and pinned_heap_16M. Each of the target heaps differ in the size of the pages that back them. kernel_heap_4K_64K or pinned_heap_4K_64K will be backed by either medium (64 KB) or regular (4 KB) pages, depending on the page size supported by the machine. kernel_heap_16M or pinned_heap_16M will return memory backed by large pages if large page heaps are enabled. If large page heaps are not enabled, kernel_heap or pinned_heap will point to the default heap. If the size of the backing pages are not important, use the kernel_heap value and the pinned_heap value. They will point to the heap that you prefer. For more information about large page heap support, see vmo.

Kernel extensions can use these services to allocate memory out of the kernel heaps. For example, the xmalloc (128,3,kernel_heap) kernel service allocates a 128-byte double word aligned area out of the kernel heap.

A kernel extension must use the xmfree kernel service to free the allocated memory. If it does not, subsequent allocations eventually are unsuccessful.

The xmalloc kernel service has two compatibility interfaces: malloc and palloc.

The following additional interfaces to the xmalloc kernel service are provided:

• malloc (size) is equivalent to xmalloc (size, 0, kernel_heap).
• palloc (size, align) is equivalent to xmalloc (size, align, kernel_heap).

Execution Environment

The xmalloc kernel service can be called from the process environment only.

Return Values

Upon successful completion, the xmalloc kernel service returns the address of the allocated area. A null pointer is returned under the following circumstances:

• The requested memory cannot be allocated.
• The heap has not been initialized for memory allocation.