1 VMEM_CREATE(9F)          Kernel Functions for Drivers          VMEM_CREATE(9F)
   2 
   3 NAME
   4      vmem_create, vmem_xcreate, vmem_destroy - create and destroy vmem arenas
   5 
   6 SYNOPSIS
   7      #include <sys/vmem.h>
   8 
   9      typedef struct vmem vmem_t;
  10      typedef void *(vmem_alloc_t)(vmem_t *, size_t, int);
  11      typedef void (vmem_free_t)(vmem_t *, void *, size_t);
  12      typedef void *(vmem_ximport_t)(vmem_t *, size_t *, size_t, int);
  13 
  14      vmem_t *
  15      vmem_create(const char *name, void *base, size_t size, size_t quantum,
  16          vmem_alloc_t *afunc, vmem_free_t *ffunc, vmem_t *source,
  17          size_t qcache_max, int vmflag);
  18 
  19      vmem_t *
  20      vmem_xcreate(const char *name, void *base, size_t size, size_t quantum,
  21          vmem_ximport_t *afunc, vmem_free_t *ffunc, vmem_t *source,
  22          size_t qcache_max, int vmflag);
  23 
  24      void
  25      vmem_destroy(vmem_t *vmp);
  26 
  27 INTERFACE LEVEL
  28      illumos DDI specific
  29 
  30 PARAMETERS
  31      name    A character string giving a name to the vmem arena to be created.
  32 
  33      base    An address indicating the lowest possible value in the arena.
  34 
  35      size    The size of the arena to create.
  36 
  37      quantum
  38              The arena's ``quantum''.  The granularity of the arena.  The
  39              amount allocated at minimum by each request.  Must be a power of
  40              2.
  41 
  42      afunc   A function which is called to import new spans from source, which
  43              may be NULL if this arena does not import from another.  When
  44              calling vmem_create(), afunc is a vmem_alloc_t, a function taking
  45              three parameters and returning a pointer to void (the imported
  46              space):
  47 
  48              vmem_t *
  49                      The source arena from which we'll import.  The source
  50                      argument to vmem_create().
  51 
  52              size_t  The size to import.
  53 
  54              int     The vmflag argument used for the import.
  55 
  56              When calling vmem_xcreate(), afunc is a vmem_ximport_t, a
  57              function taking four parameters and returning a pointer to void
  58              (the imported space):
  59 
  60              vmem_t *
  61                      The source arena from which we'll import.  The source
  62                      argument to vmem_xcreate().
  63 
  64              size_t *
  65                      The size of the import.  afunc may increase this size if
  66                      that is desirable, but must never decrease it.
  67 
  68              size_t  The desired alignment of the imported space.
  69 
  70              int     The vmflag argument used for the import.
  71 
  72      ffunc   A function which is called to return spans to source, which may
  73              be NULL if this arena does not import from another.  This is a
  74              vmem_free_t, a function taking three parameters and returning
  75              void:
  76 
  77              vmem_t  The arena to which space is being returned.  The source
  78                      argument to vmem_create() or vmem_xcreate().
  79 
  80              void *  The span being returned to the source arena.
  81 
  82              size_t  The size of the span being returned to the source arena.
  83 
  84      source  An arena from which this arena will import, which may be NULL if
  85              this arena does not import from another.
  86 
  87      qcache_max
  88              Each arena offers caching of integer multiples of quantum up to
  89              qcache_max, which may be 0.
  90 
  91      vmflag  A bitmask of flags indicating the characteristics of this arena.
  92 
  93              VMC_IDENTIFIER
  94                      The arena represents arbitrary integer identifiers,
  95                      rather than virtual memory.
  96 
  97      vmp     A pointer to the vmem arena to be destroyed.
  98 
  99 DESCRIPTION
 100      A vmem arena is a section of an arbitrary address space (a range of
 101      integer addresses).  This commonly represents virtual memory, but can in
 102      fact be an arbitrary set of integers. The VMC_IDENTIFIER flag set at
 103      arena creation time differentiates between these two cases.
 104 
 105      The afunc, ffunc, and source arguments combine to support a hierarchical
 106      structure of arenas, each importing from a single parent (the source).
 107      The vmem_create() and vmem_xcreate() functions differ in that the latter
 108      provides an interface for afunc to alter the size of the span imported
 109      from source.  It is only legal to increase this size.
 110 
 111 CONTEXT
 112      These functions can be called from user or kernel context.
 113 
 114 RETURN VALUES
 115      Upon successful completion the vmem_create() and vmem_xcreate() functions
 116      return a pointer to a vmem arena.  Otherwise, NULL is returned to
 117      indicate the arena could not be created.
 118 
 119 SEE ALSO
 120      vmem(9), vmem_add(9F), vmem_alloc(9F)
 121 
 122 illumos                        January 18, 2017                        illumos