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_cache_create.9f
          +++ new/usr/src/man/man9f/kmem_cache_create.9f
   1    1  '\" te
   2    2  .\" Copyright 2015 Nexenta Systems, Inc.  All rights reserved.
        3 +.\" Copyright 2022 Joyent, Inc.
   3    4  .\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved.
   4    5  .\" 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.
   5    6  .\" 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.
   6    7  .\" 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]
   7    8  .TH KMEM_CACHE_CREATE 9F "Feb 18, 2015"
   8    9  .SH NAME
   9   10  kmem_cache_create, kmem_cache_alloc, kmem_cache_free, kmem_cache_destroy,
  10   11  kmem_cache_set_move \- kernel memory cache allocator operations
  11   12  .SH SYNOPSIS
  12   13  .nf
↓ open down ↓ 149 lines elided ↑ open up ↑ 
 162  163  .RS 15n
 163  164  Allow sleeping (blocking) until memory is available.
 164  165  .RE
 165  166  
 166  167  .sp
 167  168  .ne 2
 168  169  .na
 169  170  \fB\fBKM_NOSLEEP\fR\fR
 170  171  .ad
 171  172  .RS 15n
 172      -Return NULL immediately if memory is not available.
      173 +Return NULL immediately if memory is not available, but after an aggressive
      174 +reclaiming attempt.  Any mention of \fBKM_NOSLEEP\fR without mentioning
      175 +\fBKM_NOSLEEP_LAZY\fR (see below) applies to both values.
 173  176  .RE
 174  177  
 175  178  .sp
 176  179  .ne 2
 177  180  .na
      181 +\fB\fBKM_NOSLEEP_LAZY\fR\fR
      182 +.ad
      183 +.RS 15n
      184 +Return NULL immediately if memory is not available, without the aggressive
      185 +reclaiming attempt.  This is actually two flags combined:
      186 +(\fBKM_NOSLEEP\fR | \fBKM_NORMALPRI\fR), the latter flag indicating not to
      187 +attempt reclamation before giving up and returning NULL.
      188 +.RE
      189 +
      190 +.sp
      191 +.ne 2
      192 +.na
 178  193  \fB\fBKM_PUSHPAGE\fR\fR
 179  194  .ad
 180  195  .RS 15n
 181  196  Allow the allocation to use reserved memory.
 182  197  .RE
 183  198  
 184  199  .RE
 185  200  
 186  201  .sp
 187  202  .ne 2
↓ open down ↓ 155 lines elided ↑ open up ↑ 
 343  358  memory but cannot. \fIprivate\fR is a parameter passed to the constructor and
 344  359  destructor callbacks to support parameterized caches (for example, a pointer to
 345  360  an instance of the driver's soft-state structure). To facilitate debugging,
 346  361  \fBkmem_cache_create()\fR creates a \fBkstat\fR(9S) structure of class
 347  362  \fBkmem_cache\fR and name \fIname\fR. It returns an opaque pointer to the
 348  363  object cache.
 349  364  .sp
 350  365  .LP
 351  366  \fBkmem_cache_alloc()\fR gets an object from the cache. The object will be in
 352  367  its constructed state. \fIkmflag\fR has either \fBKM_SLEEP\fR or
 353      -\fBKM_NOSLEEP\fR set, indicating whether it is acceptable to wait for memory if
 354      -none is currently available.
      368 +\fBKM_NOSLEEP\fR set, indicating whether it is acceptable to wait for memory
      369 +if none is currently available.
 355  370  .sp
 356  371  .LP
 357  372  A small pool of reserved memory is available to allow the system to progress
 358  373  toward the goal of freeing additional memory while in a low memory situation.
 359  374  The \fBKM_PUSHPAGE\fR flag enables use of this reserved memory pool on an
 360  375  allocation. This flag can be used by drivers that implement \fBstrategy\fR(9E)
 361  376  on memory allocations associated with a single I/O operation. The driver
 362  377  guarantees that the I/O operation will complete (or timeout) and, on
 363  378  completion, that the memory will be returned. The \fBKM_PUSHPAGE\fR flag should
 364  379  be used only in \fBkmem_cache_alloc()\fR calls. All allocations from a given
↓ open down ↓ 201 lines elided ↑ open up ↑ 
 566  581  allocator may also call the constructor and destructor on objects still under
 567  582  its control without client involvement.
 568  583  .sp
 569  584  .LP
 570  585  \fBkmem_cache_create()\fR and \fBkmem_cache_destroy()\fR must not be called
 571  586  from interrupt context. \fBkmem_cache_create()\fR can also block for available
 572  587  memory.
 573  588  .sp
 574  589  .LP
 575  590  \fBkmem_cache_alloc()\fR can be called from interrupt context only if the
 576      -\fBKM_NOSLEEP\fR flag is set. It can be called from user or kernel context with
 577      -any valid flag.
      591 +\fBKM_NOSLEEP\fR flag is set. It can be called from user or kernel context
      592 +with any valid flag.
 578  593  .sp
 579  594  .LP
 580  595  \fBkmem_cache_free()\fR can be called from user, kernel, or interrupt context.
 581  596  .sp
 582  597  .LP
 583  598  \fBkmem_cache_set_move()\fR is called from the same context as
 584  599  \fBkmem_cache_create()\fR, immediately after \fBkmem_cache_create()\fR and
 585  600  before allocating any objects from the cache.
 586  601  .sp
 587  602  .LP
↓ open down ↓ 114 lines elided ↑ open up ↑ 
 702  717  
 703  718  .sp
 704  719  .in +2
 705  720  .nf
 706  721  object_cache = kmem_cache_create(...);
 707  722  kmem_cache_set_move(object_cache, object_move);
 708  723  .fi
 709  724  .in -2
 710  725  
 711  726  .SH RETURN VALUES
 712      -If successful, the constructor function must return \fB0\fR. If KM_NOSLEEP is
 713      -set and memory cannot be allocated without sleeping, the constructor must
 714      -return -\fB1\fR.
      727 +If successful, the constructor function must return \fB0\fR. If
      728 +\fBKM_NOSLEEP\fR or \fBKM_NOSLEEP_LAZY\fR is set and memory cannot be
      729 +allocated without sleeping, the constructor must return -\fB1\fR.  If the
      730 +constructor takes extraordinary steps during a \fBKM_NOSLEEP\fR construction,
      731 +it may not take those for a \fBKM_NOSLEEP_LAZY\fR construction.
 715  732  .sp
 716  733  .LP
 717  734  \fBkmem_cache_create()\fR returns a pointer to the allocated cache.
 718  735  .sp
 719  736  .LP
 720  737  If successful, \fBkmem_cache_alloc()\fR returns a pointer to the allocated
 721  738  object. If \fBKM_NOSLEEP\fR is set and memory cannot be allocated without
 722  739  sleeping, \fBkmem_cache_alloc()\fR returns \fBNULL\fR.
 723  740  .SH ATTRIBUTES
 724  741  See \fBattributes\fR(5) for descriptions of the following attributes:
↓ open down ↓ 39 lines elided ↑ open up ↑ 
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX