1 '\" te
   2 .\" Copyright 2014 Nexenta Systems, Inc.  All rights reserved.

   3 .\"  Copyright 1989 AT&T
   4 .\"  Copyright (c) 2006, Sun Microsystems, Inc.,  All Rights Reserved
   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.
   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.
   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]
   8 .TH KMEM_ALLOC 9F "Nov 20, 2019"
   9 .SH NAME
  10 kmem_alloc, kmem_zalloc, kmem_free \- allocate kernel memory
  11 .SH SYNOPSIS
  12 .nf
  13 #include <sys/types.h>
  14 #include <sys/kmem.h>
  15 
  16 
  17 
  18 \fBvoid *\fR\fBkmem_alloc\fR(\fBsize_t\fR \fIsize\fR, \fBint\fR \fIflag\fR);
  19 .fi
  20 
  21 .LP
  22 .nf

  29 .fi
  30 
  31 .SH INTERFACE LEVEL
  32 Architecture independent level 1 (DDI/DKI).
  33 .SH PARAMETERS
  34 .ne 2
  35 .na
  36 \fB\fIsize\fR\fR
  37 .ad
  38 .RS 8n
  39 Number of bytes to allocate.
  40 .RE
  41 
  42 .sp
  43 .ne 2
  44 .na
  45 \fB\fIflag\fR\fR
  46 .ad
  47 .RS 8n
  48 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.






  51 .RE
  52 
  53 .sp
  54 .ne 2
  55 .na
  56 \fB\fIbuf\fR\fR
  57 .ad
  58 .RS 8n
  59 Pointer to allocated memory.
  60 .RE
  61 
  62 .SH DESCRIPTION
  63 The \fBkmem_alloc()\fR function allocates \fIsize\fR bytes of kernel memory and
  64 returns a pointer to the allocated memory. The allocated memory is at least
  65 double-word aligned, so it can hold any C data structure. No greater alignment
  66 can be assumed. \fIflag\fR determines whether the caller can sleep for memory.
  67 \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.



  71 .sp
  72 .LP
  73 The \fBkmem_zalloc()\fR function is like \fBkmem_alloc()\fR but returns
  74 zero-filled memory.
  75 .sp
  76 .LP
  77 The \fBkmem_free()\fR function frees previously allocated kernel memory. The
  78 buffer address and size must exactly match the original allocation. Memory
  79 cannot be returned piecemeal.
  80 .SH RETURN VALUES
  81 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.

  84 .SH CONTEXT
  85 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.
  89 .SH SEE ALSO
  90 \fBcopyout\fR(9F), \fBfreerbuf\fR(9F), \fBgetrbuf\fR(9F)
  91 .sp
  92 .LP
  93 \fIWriting Device Drivers\fR
  94 .SH WARNINGS
  95 Memory allocated using \fBkmem_alloc()\fR is not paged. Available memory is
  96 therefore limited by the total physical memory on the system. It is also
  97 limited by the available kernel virtual address space, which is often the more
  98 restrictive constraint on large-memory configurations.
  99 .sp
 100 .LP
 101 Excessive use of kernel memory is likely to affect overall system performance.
 102 Overcommitment of kernel memory will cause the system to hang or panic.
 103 .sp
 104 .LP
 105 Misuse of the kernel memory allocator, such as writing past the end of a
 106 buffer, using a buffer after freeing it, freeing a buffer twice, or freeing a
 107 null or invalid pointer, will corrupt the kernel heap and may cause the system
 108 to corrupt data or panic.

   1 '\" te
   2 .\" Copyright 2014 Nexenta Systems, Inc.  All rights reserved.
   3 .\" Copyright 2022 Joyent, Inc.
   4 .\"  Copyright 1989 AT&T
   5 .\"  Copyright (c) 2006, Sun Microsystems, Inc.,  All Rights Reserved
   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.
   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.
   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]
   9 .TH KMEM_ALLOC 9F "Nov 20, 2019"
  10 .SH NAME
  11 kmem_alloc, kmem_zalloc, kmem_free \- allocate kernel memory
  12 .SH SYNOPSIS
  13 .nf
  14 #include <sys/types.h>
  15 #include <sys/kmem.h>
  16 
  17 
  18 
  19 \fBvoid *\fR\fBkmem_alloc\fR(\fBsize_t\fR \fIsize\fR, \fBint\fR \fIflag\fR);
  20 .fi
  21 
  22 .LP
  23 .nf

  30 .fi
  31 
  32 .SH INTERFACE LEVEL
  33 Architecture independent level 1 (DDI/DKI).
  34 .SH PARAMETERS
  35 .ne 2
  36 .na
  37 \fB\fIsize\fR\fR
  38 .ad
  39 .RS 8n
  40 Number of bytes to allocate.
  41 .RE
  42 
  43 .sp
  44 .ne 2
  45 .na
  46 \fB\fIflag\fR\fR
  47 .ad
  48 .RS 8n
  49 Determines whether caller can sleep for memory. Possible flags are
  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.
  58 .RE
  59 
  60 .sp
  61 .ne 2
  62 .na
  63 \fB\fIbuf\fR\fR
  64 .ad
  65 .RS 8n
  66 Pointer to allocated memory.
  67 .RE
  68 
  69 .SH DESCRIPTION
  70 The \fBkmem_alloc()\fR function allocates \fIsize\fR bytes of kernel memory and
  71 returns a pointer to the allocated memory. The allocated memory is at least
  72 double-word aligned, so it can hold any C data structure. No greater alignment
  73 can be assumed. \fIflag\fR determines whether the caller can sleep for memory.
  74 \fBKM_SLEEP\fR allocations may sleep but are guaranteed to succeed.
  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.
  81 .sp
  82 .LP
  83 The \fBkmem_zalloc()\fR function is like \fBkmem_alloc()\fR but returns
  84 zero-filled memory.
  85 .sp
  86 .LP
  87 The \fBkmem_free()\fR function frees previously allocated kernel memory. The
  88 buffer address and size must exactly match the original allocation. Memory
  89 cannot be returned piecemeal.
  90 .SH RETURN VALUES
  91 If successful, \fBkmem_alloc()\fR and \fBkmem_zalloc()\fR return a pointer to
  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.
  95 .SH CONTEXT
  96 The \fBkmem_alloc()\fR and \fBkmem_zalloc()\fR functions can be called from
  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.
 100 .SH SEE ALSO
 101 \fBcopyout\fR(9F), \fBfreerbuf\fR(9F), \fBgetrbuf\fR(9F)
 102 .sp
 103 .LP
 104 \fIWriting Device Drivers\fR
 105 .SH WARNINGS
 106 Memory allocated using \fBkmem_alloc()\fR is not paged. Available memory is
 107 therefore limited by the total physical memory on the system. It is also
 108 limited by the available kernel virtual address space, which is often the more
 109 restrictive constraint on large-memory configurations.
 110 .sp
 111 .LP
 112 Excessive use of kernel memory is likely to affect overall system performance.
 113 Overcommitment of kernel memory will cause the system to hang or panic.
 114 .sp
 115 .LP
 116 Misuse of the kernel memory allocator, such as writing past the end of a
 117 buffer, using a buffer after freeing it, freeing a buffer twice, or freeing a
 118 null or invalid pointer, will corrupt the kernel heap and may cause the system
 119 to corrupt data or panic.