trusty (9) contigmalloc.9freebsd.gz

NAME

     contigmalloc, contigfree — manage contiguous kernel physical memory

SYNOPSIS

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

     void *
     contigmalloc(unsigned long size, struct malloc_type *type, int flags, vm_paddr_t low, vm_paddr_t high,
         unsigned long alignment, unsigned long boundary);

     void
     contigfree(void *addr, unsigned long size, struct malloc_type *type);

DESCRIPTION

     The contigmalloc() function allocates size bytes of contiguous physical memory that is aligned to alignment
     bytes, and which does not cross a boundary of boundary bytes.  If successful, the allocation will reside
     between physical addresses low and high.  The returned pointer points to a wired kernel virtual address
     range of size bytes allocated from the kernel virtual address (KVA) map.

     The flags parameter modifies contigmalloc()'s behaviour as follows:

     M_ZERO  Causes the allocated physical memory to be zero filled.

     M_NOWAIT
             Causes contigmalloc() to return NULL if the request cannot be immediately fulfilled due to resource
             shortage.

     Other flags (if present) are ignored.

     The contigfree() function deallocates memory allocated by a previous call to contigmalloc().

IMPLEMENTATION NOTES

     The contigmalloc() function does not sleep waiting for memory resources to be freed up, but instead
     actively reclaims pages before giving up.  However, unless M_NOWAIT is specified, it may select a page for
     reclamation that must first be written to backing storage, causing it to sleep.

RETURN VALUES

     The contigmalloc() function returns a kernel virtual address if allocation succeeds, or NULL otherwise.

EXAMPLES

     void *p;
     p = contigmalloc(8192, M_DEVBUF, M_ZERO, 0, (1L << 22),
         32 * 1024, 1024 * 1024);

     Ask for 8192 bytes of zero-filled memory residing between physical address 0 and 4194303 inclusive, aligned
     to a 32K boundary and not crossing a 1M address boundary.

DIAGNOSTICS

     The contigmalloc() function will panic if size is zero, or if alignment or boundary is not a power of two.

SEE ALSO

     malloc(9), memguard(9)