Print this page 
5513 KM_NORMALPRI should be documented in kmem_alloc(9f) and kmem_cache_create(9f) man pages
14465 Present KM_NOSLEEP_LAZY as documented interface
Change-Id: I002ec28ddf390650f1fcba1ca94f6abfdb241439
Split Close
Expand all
Collapse all
          --- old/usr/src/man/man9f/kmem_alloc.9f
          +++ new/usr/src/man/man9f/kmem_alloc.9f
   1    1  '\" te
   2    2  .\" Copyright 2014 Nexenta Systems, Inc.  All rights reserved.
        3 +.\" Copyright 2022 Joyent, Inc.
   3    4  .\"  Copyright 1989 AT&T
   4    5  .\"  Copyright (c) 2006, Sun Microsystems, Inc.,  All Rights Reserved
   5    6  .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   6    7  .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   7    8  .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   8    9  .TH KMEM_ALLOC 9F "Nov 20, 2019"
   9   10  .SH NAME
  10   11  kmem_alloc, kmem_zalloc, kmem_free \- allocate kernel memory
  11   12  .SH SYNOPSIS
  12   13  .nf
↓ open down ↓ 26 lines elided ↑ open up ↑ 
  39   40  Number of bytes to allocate.
  40   41  .RE
  41   42  
  42   43  .sp
  43   44  .ne 2
  44   45  .na
  45   46  \fB\fIflag\fR\fR
  46   47  .ad
  47   48  .RS 8n
  48   49  Determines whether caller can sleep for memory. Possible flags are
  49      -\fBKM_SLEEP\fR to allow sleeping until memory is available, or \fBKM_NOSLEEP\fR
  50      -to return \fINULL\fR immediately if memory is not available.
       50 +\fBKM_SLEEP\fR to allow sleeping until memory is available, \fBKM_NOSLEEP\fR
       51 +to return \fINULL\fR if memory is not available even after some reclamation
       52 +attempts, and \fBKM_NOSLEEP_LAZY\fR to return \fINULL\fR without reclamation
       53 +attempts.  \fBKM_NOSLEEP_LAZY\fR is actually two flags combined:
       54 +(\fBKM_NOSLEEP\fR | \fBKM_NORMALPRI\fR), the latter flag indicating not to
       55 +attempt reclamation before giving up and returning NULL.  If any mention of
       56 +\fBKM_NOSLEEP\fR appears in this man page by itself, it applies equally to
       57 +\fBKM_NOSLEEP_LAZY\fR as well.
  51   58  .RE
  52   59  
  53   60  .sp
  54   61  .ne 2
  55   62  .na
  56   63  \fB\fIbuf\fR\fR
  57   64  .ad
  58   65  .RS 8n
  59   66  Pointer to allocated memory.
  60   67  .RE
  61   68  
  62   69  .SH DESCRIPTION
  63   70  The \fBkmem_alloc()\fR function allocates \fIsize\fR bytes of kernel memory and
  64   71  returns a pointer to the allocated memory. The allocated memory is at least
  65   72  double-word aligned, so it can hold any C data structure. No greater alignment
  66   73  can be assumed. \fIflag\fR determines whether the caller can sleep for memory.
  67   74  \fBKM_SLEEP\fR allocations may sleep but are guaranteed to succeed.
  68      -\fBKM_NOSLEEP\fR allocations are guaranteed not to sleep but may fail (return
  69      -\fINULL\fR) if no memory is currently available. The initial contents of memory
  70      -allocated using \fBkmem_alloc()\fR are random garbage.
       75 +\fBKM_NOSLEEP\fR and \fBKM_NOSLEEP_LAZY\fR allocations are guaranteed not to
       76 +sleep but may fail (return \fINULL\fR) if no memory is currently
       77 +available. \fBKM_NOSLEEP\fR will first attempt to aggressively reclaim memory
       78 +from otherwise unused blocks, while \fBKM_NOSLEEP_LAZY\fR will not attempt any
       79 +reclamation. The initial contents of memory allocated using
       80 +\fBkmem_alloc()\fR are random garbage.
  71   81  .sp
  72   82  .LP
  73   83  The \fBkmem_zalloc()\fR function is like \fBkmem_alloc()\fR but returns
  74   84  zero-filled memory.
  75   85  .sp
  76   86  .LP
  77   87  The \fBkmem_free()\fR function frees previously allocated kernel memory. The
  78   88  buffer address and size must exactly match the original allocation. Memory
  79   89  cannot be returned piecemeal.
  80   90  .SH RETURN VALUES
  81   91  If successful, \fBkmem_alloc()\fR and \fBkmem_zalloc()\fR return a pointer to
  82      -the allocated memory. If \fBKM_NOSLEEP\fR is set and memory cannot be allocated
  83      -without sleeping, \fBkmem_alloc()\fR and \fBkmem_zalloc()\fR return \fINULL\fR.
       92 +the allocated memory. If \fBKM_NOSLEEP\fR is set and memory cannot be
       93 +allocated without sleeping, \fBkmem_alloc()\fR and \fBkmem_zalloc()\fR return
       94 +\fINULL\fR.
  84   95  .SH CONTEXT
  85   96  The \fBkmem_alloc()\fR and \fBkmem_zalloc()\fR functions can be called from
  86      -interrupt context only if the \fBKM_NOSLEEP\fR flag is set. They can be called
  87      -from user context with any valid \fIflag\fR. The \fBkmem_free()\fR function can
  88      -be called from from user, interrupt, or kernel context.
       97 +interrupt context only if the \fBKM_NOSLEEP\fR flag is set. They can be
       98 +called from user context with any valid \fIflag\fR. The \fBkmem_free()\fR
       99 +function can be called from from user, interrupt, or kernel context.
  89  100  .SH SEE ALSO
  90  101  \fBcopyout\fR(9F), \fBfreerbuf\fR(9F), \fBgetrbuf\fR(9F)
  91  102  .sp
  92  103  .LP
  93  104  \fIWriting Device Drivers\fR
  94  105  .SH WARNINGS
  95  106  Memory allocated using \fBkmem_alloc()\fR is not paged. Available memory is
  96  107  therefore limited by the total physical memory on the system. It is also
  97  108  limited by the available kernel virtual address space, which is often the more
  98  109  restrictive constraint on large-memory configurations.
↓ open down ↓ 22 lines elided ↑ open up ↑ 
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX