VMEM_CREATE(9F) Kernel Functions for Drivers VMEM_CREATE(9F)

NAME

vmem_create, vmem_xcreate, vmem_destroy - create and destroy vmem arenas

SYNOPSIS

#include <sys/vmem.h>

typedef struct vmem vmem_t;
typedef void *(vmem_alloc_t)(vmem_t *, size_t, int);
typedef void (vmem_free_t)(vmem_t *, void *, size_t);
typedef void *(vmem_ximport_t)(vmem_t *, size_t *, size_t, int);

vmem_t *
vmem_create(const char *name, void *base, size_t size, size_t quantum,
vmem_alloc_t *afunc, vmem_free_t *ffunc, vmem_t *source,
size_t qcache_max, int vmflag);

vmem_t *
vmem_xcreate(const char *name, void *base, size_t size, size_t quantum,
vmem_ximport_t *afunc, vmem_free_t *ffunc, vmem_t *source,
size_t qcache_max, int vmflag);

void
vmem_destroy(vmem_t *vmp);

INTERFACE LEVEL

illumos DDI specific

PARAMETERS

name A character string giving a name to the vmem arena to be created.

base An address indicating the lowest possible value in the arena.

size The size of the arena to create.

quantum
The arena's "quantum". The granularity of the arena. The amount
allocated at minimum by each request. Must be a power of 2.

afunc A function which is called to import new spans from source, which
may be NULL if this arena does not import from another. When
calling vmem_create(), afunc is a vmem_alloc_t, a function taking
three parameters and returning a pointer to void (the imported
space):

vmem_t *
The source arena from which we'll import. The source
argument to vmem_create().

size_t The size to import.

int The vmflag argument used for the import.

When calling vmem_xcreate(), afunc is a vmem_ximport_t, a function
taking four parameters and returning a pointer to void (the
imported space):

vmem_t *
The source arena from which we'll import. The source
argument to vmem_xcreate().

size_t *
The size of the import. afunc may increase this size if
that is desirable, but must never decrease it.

size_t The desired alignment of the imported space.

int The vmflag argument used for the import.

ffunc A function which is called to return spans to source, which may be
NULL if this arena does not import from another. This is a
vmem_free_t, a function taking three parameters and returning void:

vmem_t The arena to which space is being returned. The source
argument to vmem_create() or vmem_xcreate().

void * The span being returned to the source arena.

size_t The size of the span being returned to the source arena.

source An arena from which this arena will import, which may be NULL if
this arena does not import from another.

qcache_max
Each arena offers caching of integer multiples of quantum up to
qcache_max, which may be 0.

vmflag A bitmask of flags indicating the characteristics of this arena.

VMC_IDENTIFIER
The arena represents arbitrary integer identifiers, rather
than virtual memory.

vmp A pointer to the vmem arena to be destroyed.

DESCRIPTION

A vmem arena is a section of an arbitrary address space (a range of integer
addresses). This commonly represents virtual memory, but can in fact be an
arbitrary set of integers. The VMC_IDENTIFIER flag set at arena creation
time differentiates between these two cases.

The afunc, ffunc, and source arguments combine to support a hierarchical
structure of arenas, each importing from a single parent (the source). The
vmem_create() and vmem_xcreate() functions differ in that the latter
provides an interface for afunc to alter the size of the span imported from
source. It is only legal to increase this size.

CONTEXT

These functions can be called from user or kernel context.

RETURN VALUES

Upon successful completion the vmem_create() and vmem_xcreate() functions
return a pointer to a vmem arena. Otherwise, NULL is returned to indicate
the arena could not be created.

SEE ALSO

vmem(9), vmem_add(9F), vmem_alloc(9F)

illumos January 18, 2017 illumos