11927 Log, or optionally panic, on zero-length kmem allocations
Reviewed by: Dan McDonald <danmcd@joyent.com>
Reviewed by: Jason King <jason.brian.king@gmail.com>

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

   1    1  KMEM_ALLOC(9F)           Kernel Functions for Drivers           KMEM_ALLOC(9F)
   2    2  
   3    3  
   4    4  
   5    5  NAME
   6    6         kmem_alloc, kmem_zalloc, kmem_free - allocate kernel memory
   7    7  
   8    8  SYNOPSIS
   9    9         #include <sys/types.h>
  10   10         #include <sys/kmem.h>
  11   11  
  12   12  
  13   13  
  14   14         void *kmem_alloc(size_t size, int flag);
  15   15  
  16   16  
  17   17         void *kmem_zalloc(size_t size, int flag);
  18   18  
  19   19  
  20   20         void kmem_free(void *buf, size_t size);
  21   21  
  22   22  
  23   23  INTERFACE LEVEL
  24   24         Architecture independent level 1 (DDI/DKI).
  25   25  
  26   26  PARAMETERS
  27   27         size
  28   28                 Number of bytes to allocate.
  29   29  
  30   30  
  31   31         flag
  32   32                 Determines whether caller can sleep for memory. Possible flags
  33   33                 are KM_SLEEP to allow sleeping until memory is available, or
  34   34                 KM_NOSLEEP to return NULL immediately if memory is not
  35   35                 available.
  36   36  
  37   37  
  38   38         buf
  39   39                 Pointer to allocated memory.
  40   40  
  41   41  
  42   42  DESCRIPTION
  43   43         The kmem_alloc() function allocates size bytes of kernel memory and
  44   44         returns a pointer to the allocated memory. The allocated memory is at
  45   45         least double-word aligned, so it can hold any C data structure. No
  46   46         greater alignment can be assumed. flag determines whether the caller
  47   47         can sleep for memory.  KM_SLEEP allocations may sleep but are
  48   48         guaranteed to succeed.  KM_NOSLEEP allocations are guaranteed not to
  49   49         sleep but may fail (return NULL) if no memory is currently available.
  50   50         The initial contents of memory allocated using kmem_alloc() are random
  51   51         garbage.
  52   52  
  53   53  
  54   54         The kmem_zalloc() function is like kmem_alloc() but returns zero-filled
  55   55         memory.
  56   56  
  57   57  
  58   58         The kmem_free() function frees previously allocated kernel memory. The
  59   59         buffer address and size must exactly match the original allocation.
  60   60         Memory cannot be returned piecemeal.
  61   61  
  62   62  RETURN VALUES
  63   63         If successful, kmem_alloc() and kmem_zalloc() return a pointer to the
  64   64         allocated memory. If KM_NOSLEEP is set and memory cannot be allocated
  65   65         without sleeping, kmem_alloc() and kmem_zalloc() return NULL.
  66   66  
  67   67  CONTEXT
  68   68         The kmem_alloc() and kmem_zalloc() functions can be called from
  69   69         interrupt context only if the KM_NOSLEEP flag is set. They can be
  70   70         called from user context with any valid flag. The kmem_free() function
  71   71         can be called from from user, interrupt, or kernel context.
  72   72  
  73   73  SEE ALSO
  74   74         copyout(9F), freerbuf(9F), getrbuf(9F)
  75   75  
  76   76  
  77   77         Writing Device Drivers
  78   78  
  79   79  WARNINGS
  80   80         Memory allocated using kmem_alloc() is not paged. Available memory is
  81   81         therefore limited by the total physical memory on the system. It is
  82   82         also limited by the available kernel virtual address space, which is
  83   83         often the more restrictive constraint on large-memory configurations.
  84   84  
  85   85  
  86   86         Excessive use of kernel memory is likely to affect overall system
  87   87         performance.  Overcommitment of kernel memory will cause the system to
  88   88         hang or panic.
  89   89  
  90   90  
  91   91         Misuse of the kernel memory allocator, such as writing past the end of
  92   92         a buffer, using a buffer after freeing it, freeing a buffer twice, or

  93   93         freeing a null or invalid pointer, will corrupt the kernel heap and may
  94   94         cause the system to corrupt data or panic.
  95   95  
  96   96  
  97   97         The initial contents of memory allocated using kmem_alloc() are random
  98   98         garbage. This random garbage may include secure kernel data. Therefore,
  99   99         uninitialized kernel memory should be handled carefully. For example,
 100  100         never copyout(9F) a potentially uninitialized buffer.
 101  101  
 102  102  NOTES
 103      -       kmem_alloc(0, flag) always returns NULL.  kmem_free(NULL, 0) is legal.
      103 +       kmem_alloc(0, flag) always returns NULL, but if KM_SLEEP is set, this
      104 +       behavior is considered to be deprecated; the system may be configured
      105 +       to explicitly panic in this case in lieu of returning NULL.
      106 +       kmem_free(NULL, 0) is legal, however.
 104  107  
 105  108  
 106  109  
 107      -                               October 22, 2014                 KMEM_ALLOC(9F)
      110 +                               November 20, 2019                KMEM_ALLOC(9F)
    

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX