code review from Josh and Robert

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

   1    1  VMEM_ALLOC(9F)           Kernel Functions for Drivers           VMEM_ALLOC(9F)
   2    2  
   3    3  NAME
   4    4       vmem_alloc, vmem_xalloc, vmem_free, vmem_xfree - allocate and free
   5    5       segments from a vmem arena
   6    6  
   7    7  SYNOPSIS
   8    8       #include <sys/vmem.h>
   9    9  
  10   10       void *
  11   11       vmem_alloc(vmem_t *vmp, size_t size, int vmflag);
  12   12  
  13   13       void *
  14   14       vmem_xalloc(vmem_t *vmp, size_t size, size_t align_arg, size_t phase,
  15   15           size_t nocross, void *minaddr, void *maxaddr, int vmflag);
  16   16  
  17   17       void
  18   18       vmem_free(vmem_t *vmp, void *vaddr, size_t size);
  19   19  
  20   20       void
  21   21       vmem_xfree(vmem_t *vmp, void *vaddr, size_t size);
  22   22  
  23   23  INTERFACE LEVEL
  24   24       illumos DDI specific
  25   25  
  26   26  PARAMETERS
  27   27       vmp     The vmem arena from which to allocate or free.
  28   28  
  29   29       size    The size of the segment to allocate or free.
  30   30  

  31   31       vmflag  A bitmask of flags controlling the behaviour of the allocation.
  32   32               There are two meaningful groups of flags.  VM_SLEEP or VM_NOSLEEP
  33   33               must be specified, and indicate whether the allocation may block.
  34   34               A VM_SLEEP allocation can never fail but may block indefinitely.
  35   35  
  36   36               The allocation policy may be specified by one of the following
  37   37               flags:
  38   38  
  39   39               VM_BESTFIT
  40   40                       Take the segment from the smallest free segment that
  41      -                     could satisfy this allocation
       41 +                     could satisfy this allocation.
  42   42  
  43   43               VM_FIRSTFIT
  44   44                       Take the segment from the first free segment found that
  45   45                       could satisfy this allocation.
  46   46  
  47   47               VM_NEXTFIT
  48   48                       Take the segment from the segment after the one
  49   49                       previously allocated.  This provides sequential behaviour
  50   50                       useful when allocating identifiers from a VMC_IDENTIFIER
  51   51                       arena.
  52   52  
  53   53               VM_ENDALLOC
  54   54                       May be specified in combination with VM_BESTFIT,
  55   55                       VM_FIRSTFIT or the default policy to indicate that the
  56   56                       higher addresses should be preferred.
  57   57  
  58      -             The default (un-named) allocation policy is ``instant fit'' an
       58 +             The default (unnamed) allocation policy is ``instant fit'', an
  59   59               approximation of VM_BESTFIT in guaranteed constant time.
  60   60  
  61   61       align_arg
  62      -             The minimum alignment of the allocation.  If `0' the allocated
       62 +             The minimum alignment of the allocation.  If 0, the allocated
  63   63               segment will be aligned as the arena's quantum.
  64   64  
  65   65       phase   The allocated segment must be phase bytes from the alignment
  66   66               boundary.
  67   67  
  68   68       nocross
  69   69               The allocated segment may not straddle a nocross alignment
  70   70               boundary.
  71   71  
  72   72       minaddr

  73   73               The minimum address at which the segment may be allocated.
  74   74  

  75   75       maxaddr
  76   76               The maximum address which may be included in the segment.
  77   77  
  78   78       vaddr   The address of the segment which vmem_free() or vmem_xfree()
  79   79               should free.
  80   80  
  81   81  DESCRIPTION
  82   82       The vmem_alloc() and vmem_xalloc() functions allocate a segment of size
  83   83       length from the vmem arena vmp.
  84   84  
  85      -     The vmflag argument controls the behaviour of the allocation.  As
  86      -     described in PARAMETERS
       85 +     The vmflag argument controls the behaviour of the allocation, as
       86 +     described in PARAMETERS.
  87   87  
  88   88       For allocations with complex requirements, such as those used for DMA
  89   89       vmem_xalloc() takes additional arguments allowing those requirements to
  90   90       be expressed.
  91   91  
  92   92       Segments allocated with vmem_xalloc() must always be freed with
  93   93       vmem_xfree(), since these allocations are uncached.
  94   94  
  95   95  CONTEXT
  96   96       This function can be called from either user or kernel context.  If the

  97   97       VM_NOSLEEP flag is specified, it may also be called from interrupt
  98   98       context.
  99   99  

 100  100  RETURN VALUES
 101  101       Upon successful completion the vmem_alloc() and vmem_xalloc() functions
 102  102       return a pointer to the beginning of the allocated segment.  In the case
 103  103       of a VMC_IDENTIFIER arena, the address of this pointer is the meaningful
 104  104       component, not the value to which it points.
 105  105  
 106  106       On failure, NULL is returned.  When the VM_SLEEP flag is specified, these
 107  107       functions can never fail (but may block forever).
 108  108  
 109  109  SEE ALSO
 110      -     vmem(9), vmem_create(9F)
      110 +     vmem(9), vmem_contains(9F), vmem_create(9F)
 111  111  
 112  112  illumos                        January 18, 2017                        illumos
    

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX