code review from Josh and Robert

          --- old/usr/src/man/man9f/vmem_create.9f
          +++ new/usr/src/man/man9f/vmem_create.9f

   1    1  .\"
   2    2  .\" This file and its contents are supplied under the terms of the
   3    3  .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4    4  .\" You may only use this file in accordance with the terms of version
   5    5  .\" 1.0 of the CDDL.
   6    6  .\"
   7    7  .\" A full copy of the text of the CDDL should have accompanied this
   8    8  .\" source.  A copy of the CDDL is also available via the Internet at
   9    9  .\" http://www.illumos.org/license/CDDL.
  10   10  .\"
  11   11  .\"
  12   12  .\" Copyright 2017, Richard Lowe.
  13   13  .\"
  14   14  .Dd Jan 18, 2017
  15   15  .Dt VMEM_CREATE 9F
  16   16  .Os
  17   17  .Sh NAME
  18   18  .Nm vmem_create ,
  19   19  .Nm vmem_xcreate ,
  20   20  .Nm vmem_destroy
  21   21  .Nd create and destroy vmem arenas
  22   22  .Sh SYNOPSIS
  23   23  .In sys/vmem.h
  24   24  .Vt "typedef struct vmem vmem_t;"
  25   25  .Vt "typedef void *(vmem_alloc_t)(vmem_t *, size_t, int);"
  26   26  .Vt "typedef void (vmem_free_t)(vmem_t *, void *, size_t);"
  27   27  .Vt "typedef void *(vmem_ximport_t)(vmem_t *, size_t *, size_t, int);"
  28   28  .Ft vmem_t *
  29   29  .Fo vmem_create
  30   30  .Fa "const char *name"
  31   31  .Fa "void *base"
  32   32  .Fa "size_t size"
  33   33  .Fa "size_t quantum"
  34   34  .Fa "vmem_alloc_t *afunc"
  35   35  .Fa "vmem_free_t *ffunc"
  36   36  .Fa "vmem_t *source"
  37   37  .Fa "size_t qcache_max"
  38   38  .Fa "int vmflag"
  39   39  .Fc
  40   40  .Ft vmem_t *
  41   41  .Fo vmem_xcreate
  42   42  .Fa "const char *name"
  43   43  .Fa "void *base"
  44   44  .Fa "size_t size"
  45   45  .Fa "size_t quantum"
  46   46  .Fa "vmem_ximport_t *afunc"
  47   47  .Fa "vmem_free_t *ffunc"
  48   48  .Fa "vmem_t *source"
  49   49  .Fa "size_t qcache_max"
  50   50  .Fa "int vmflag"
  51   51  .Fc
  52   52  .Ft void
  53   53  .Fo vmem_destroy
  54   54  .Fa "vmem_t *vmp"
  55   55  .Fc

  56   56  .Sh INTERFACE LEVEL
  57   57  illumos DDI specific
  58   58  .Sh PARAMETERS
  59   59  .Bl -tag -width Ds
  60   60  .It Fa name
  61   61  A character string giving a name to the vmem
  62   62  arena to be created.
  63   63  .It Fa base
  64   64  An address indicating the lowest possible value in the arena.
  65   65  .It Fa size
  66      -The size of the arena to create
       66 +The size of the arena to create.
  67   67  .It Fa quantum
  68   68  The arena's
  69   69  .Dq quantum .
  70      -The granularity of the arena.  The amount allocated at minimum by each request.
       70 +The granularity of the arena.  The amount allocated at minimum by each
       71 +request.  Must be a power of 2.
  71   72  .It Fa afunc
  72   73  A function which is called to import new spans from
  73      -.Fa source .
  74      -Which may be
       74 +.Fa source ,
       75 +which may be
  75   76  .Dv NULL
  76   77  if this arena does not import from another.
       78 +When calling
       79 +.Fn vmem_create
       80 +.Fa afunc
       81 +is an
       82 +.Vt vmem_alloc_t
       83 +a function taking three parameters and returning a pointer to
       84 +.Vt void
       85 +(the imported space):
       86 +.Bl -tag -width Ds
       87 +.It Fa "vmem_t *"
       88 +The source arena from which we'll import.  The
       89 +.Fa source
       90 +argument to
       91 +.Fn vmem_create .
       92 +.It Fa size_t
       93 +The size to import
       94 +.It Fa int
       95 +The
       96 +.Fa vmflag
       97 +argument used for the import.
       98 +.El
       99 +.Pp
      100 +When calling
      101 +.Fn vmem_xcreate
      102 +.Fa afunc
      103 +is an
      104 +.Vt vmem_ximport_t
      105 +a function taking four parameters and returning a pointer to
      106 +.Vt void
      107 +(the imported space):
      108 +.Bl -tag -width Ds
      109 +.It Fa "vmem_t *"
      110 +The source arena from which we'll import.  The
      111 +.Fa source
      112 +argument to
      113 +.Fn vmem_xcreate .
      114 +.It Fa "size_t *"
      115 +The size of the import,
      116 +.Fa afunc
      117 +may
      118 +.Em increase
      119 +this size if that is desirable, but must never decrease it.
      120 +.It Fa size_t
      121 +The desired alignment of the imported space.
      122 +.It Fa int
      123 +the
      124 +.Fa vmflag
      125 +argument used for the import.
      126 +.El
  77  127  .It Fa ffunc
  78  128  A function which is called to return spans to
  79      -.Fa source .
  80      -Which may be
      129 +.Fa source ,
      130 +which may be
  81  131  .Dv NULL
  82  132  if this arena does not import from another.
      133 +This is a
      134 +.Vt vmem_free_t
      135 +a function taking three parametes and returning void:
      136 +.Bl -tag -width Ds
      137 +.It Fa "vmem_t"
      138 +The arena to which space is being returned.  The
      139 +.Fa source
      140 +argument to
      141 +.Fn vmem_create
      142 +or
      143 +.Fn vmem_xcreate .
      144 +.It Fa "void *"
      145 +The span being returned to the source arena.
      146 +.It Fa "size_t"
      147 +The size of the span being returned to the source arena.
      148 +.El
  83  149  .It Fa source
  84      -An arena from which this arena will import.
  85      -Which may be
      150 +An arena from which this arena will import,
      151 +which may be
  86  152  .Dv NULL
  87  153  if this arena does not import from another.
  88  154  .It Fa qcache_max
  89  155  Each arena offers caching of integer multiples of
  90  156  .Fa quantum
  91  157  up to
  92      -.Fa qcache_max .
      158 +.Fa qcache_max ,
      159 +which may be 0.
  93  160  .It Fa vmflag
  94  161  A bitmask of flags indicating the characteristics of this arena.
  95  162  .Bl -tag -width Ds
  96  163  .It Dv VMC_IDENTIFIER
  97  164  The arena represents arbitrary integer identifiers, rather than virtual
  98  165  memory.
  99  166  .El
 100  167  .It Fa vmp
 101  168  A pointer to the vmem arena to be destroyed.
 102  169  .El

 103  170  .Sh DESCRIPTION
 104  171  A
 105  172  .Em vmem arena
 106  173  is a section of an arbitrary address space (a range of integer addresses).
 107  174  This commonly represents virtual memory, but can in fact be an arbitrary set
 108  175  of integers. The
 109  176  .Dv VMC_IDENTIFIER
 110  177  flag set at arena creation time differentiates between these two cases.
 111  178  .Pp
 112  179  The
 113  180  .Fa afunc ,
 114  181  .Fa ffunc , and
 115  182  .Fa source
 116  183  arguments combine to support a hierarchical structure of arenas, each
 117  184  importing from a single parent (the
 118  185  .Fa source ) .

 119  186  The
 120  187  .Fn vmem_create
 121  188  and
 122  189  .Fn vmem_xcreate
 123  190  functions differ in that the latter provides an interface for
 124  191  .Fa afunc
 125  192  to alter the size of the span imported from
 126  193  .Fa source .
 127  194  It is only legal to
 128  195  .Em increase
 129      -thise size.
      196 +this size.
 130  197  .Sh CONTEXT
 131  198  These functions can be called from user or kernel context.
 132  199  .Sh RETURN VALUES
 133  200  Upon successful completion the
 134      -.Fn vmem_create and
      201 +.Fn vmem_create
      202 +and
 135  203  .Fn vmem_xcreate
 136  204  functions return a pointer to a vmem arena.  Otherwise,
 137  205  .Dv NULL
 138  206  is returned to indicate the arena could not be created.
 139  207  .Sh SEE ALSO
 140  208  .Xr vmem 9 ,
 141  209  .Xr vmem_add 9F ,
 142  210  .Xr vmem_alloc 9F
    

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX