share/man/man9f/ddi_umem_alloc.9f

   1 '\" te
   2 .\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" Copyright 1989 AT&T
   4 .\" 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 .\" 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 .\" 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 .TH DDI_UMEM_ALLOC 9F "Mar 19, 2002"
   8 .SH NAME
   9 ddi_umem_alloc, ddi_umem_free \- allocate and free page-aligned kernel memory
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/types.h>
  14 #include <sys/sunddi.h>
  15
  16 \fBvoid *\fR\fBddi_umem_alloc\fR(\fBsize_t\fR \fIsize\fR, \fBint\fR \fIflag\fR,
  17      \fBddi_umem_cookie_t *\fR\fIcookiep\fR);
  18 .fi
  19
  20 .LP
  21 .nf
  22 \fBvoid\fR \fBddi_umem_free\fR(\fBddi_umem_cookie_t\fR \fIcookie\fR);
  23 .fi
  24
  25 .SH INTERFACE LEVEL
  26 .sp
  27 .LP
  28 Solaris DDI specific (Solaris DDI).
  29 .SH PARAMETERS
  30 .SS "ddi_umem_alloc()"
  31 .sp
  32 .ne 2
  33 .na
  34 \fB\fIsize\fR\fR
  35 .ad
  36 .RS 11n
  37 Number of bytes to allocate.
  38 .RE
  39
  40 .sp
  41 .ne 2
  42 .na
  43 \fB\fIflag\fR\fR
  44 .ad
  45 .RS 11n
  46 Used to determine the sleep and pageable conditions.
  47 .sp
  48 Possible sleep flags are \fBDDI_UMEM_SLEEP\fR, which allows sleeping until
  49 memory is available, and \fBDDI_UMEM_NOSLEEP\fR, which returns \fBNULL\fR
  50 immediately if memory is not available.
  51 .sp
  52 The default condition is to allocate locked memory; this can be changed to
  53 allocate pageable memory using the \fBDDI_UMEM_PAGEABLE\fR flag.
  54 .RE
  55
  56 .sp
  57 .ne 2
  58 .na
  59 \fB\fIcookiep\fR\fR
  60 .ad
  61 .RS 11n
  62 Pointer to a kernel memory cookie.
  63 .RE
  64
  65 .SS "ddi_umem_free()"
  66 .sp
  67 .ne 2
  68 .na
  69 \fB\fIcookie\fR\fR
  70 .ad
  71 .RS 10n
  72 A kernel memory cookie allocated in \fBddi_umem_alloc()\fR.
  73 .RE
  74
  75 .SH DESCRIPTION
  76 .sp
  77 .LP
  78 \fBddi_umem_alloc()\fR allocates page-aligned kernel memory and returns a
  79 pointer to the allocated memory. The number of bytes allocated is a multiple of
  80 the system page size (roundup of \fIsize\fR). The allocated memory can be used
  81 in the kernel and can be exported to user space. See \fBdevmap\fR(9E) and
  82 \fBdevmap_umem_setup\fR(9F) for further information.
  83 .sp
  84 .LP
  85 \fIflag\fR determines whether the caller can sleep for memory and whether the
  86 allocated memory is locked or not. \fBDDI_UMEM_SLEEP\fR allocations may sleep
  87 but are guaranteed to succeed. \fBDDI_UMEM_NOSLEEP\fR allocations do not sleep
  88 but may fail (return \fINULL\fR) if memory is currently unavailable. If
  89 \fBDDI_UMEM_PAGEABLE\fR is set, pageable memory will be allocated. These pages
  90 can be swapped out to secondary memory devices. The initial contents of memory
  91 allocated using \fBddi_umem_alloc()\fR is zero-filled.
  92 .sp
  93 .LP
  94 \fI*cookiep\fR is a pointer to the kernel memory cookie that describes the
  95 kernel memory being allocated. A typical use of \fIcookiep\fR is in
  96 \fBdevmap_umem_setup\fR(9F) when the drivers want to export the kernel memory
  97 to a user application.
  98 .sp
  99 .LP
 100 To free the allocated memory, a driver calls \fBddi_umem_free()\fR with the
 101 cookie obtained from \fBddi_umem_alloc()\fR. \fBddi_umem_free()\fR releases the
 102 entire buffer.
 103 .SH RETURN VALUES
 104 .sp
 105 .ne 2
 106 .na
 107 \fB\fBNon-null\fR\fR
 108 .ad
 109 .RS 12n
 110 Successful completion. \fBddi_umem_alloc()\fR returns a pointer to the
 111 allocated memory.
 112 .RE
 113
 114 .sp
 115 .ne 2
 116 .na
 117 \fB\fBNULL\fR\fR
 118 .ad
 119 .RS 12n
 120 Memory cannot be allocated by \fBddi_umem_alloc()\fR because
 121 \fBDDI_UMEM_NOSLEEP\fR is set and the system is out of resources.
 122 .RE
 123
 124 .SH CONTEXT
 125 .sp
 126 .LP
 127 \fBddi_umem_alloc()\fR can be called from any context if \fIflag\fR is set to
 128 \fBDDI_UMEM_NOSLEEP.\fR If \fBDDI_UMEM_SLEEP\fR is set, \fBddi_umem_alloc()\fR
 129 can be called from user and kernel context only. \fBddi_umem_free()\fR can be
 130 called from any context.
 131 .SH SEE ALSO
 132 .sp
 133 .LP
 134 \fBdevmap\fR(9E), \fBcondvar\fR(9F), \fBdevmap_umem_setup\fR(9F),
 135 \fBkmem_alloc\fR(9F), \fBmutex\fR(9F), \fBrwlock\fR(9F), \fBsemaphore\fR(9F)
 136 .sp
 137 .LP
 138 \fIWriting Device Drivers\fR
 139 .SH WARNINGS
 140 .sp
 141 .LP
 142 Setting the \fBDDI_UMEM_PAGEABLE\fR flag in \fBddi_umem_alloc()\fR will result
 143 in an allocation of pageable memory. Because these pages can be swapped out to
 144 secondary memory devices, drivers should use this flag with care. This memory
 145 must not be used for the following purposes:
 146 .RS +4
 147 .TP
 148 .ie t \(bu
 149 .el o
 150 For synchronization objects such as locks and condition variables. See
 151 \fBmutex\fR(9F), \fBsemaphore\fR(9F), \fBrwlock\fR(9F), and \fBcondvar\fR(9F).
 152 .RE
 153 .RS +4
 154 .TP
 155 .ie t \(bu
 156 .el o
 157 For driver interrupt routines.
 158 .RE
 159 .sp
 160 .LP
 161 Memory allocated using \fBddi_umem_alloc()\fR without setting
 162 \fBDDI_UMEM_PAGEABLE\fR flag cannot be paged. Available memory is therefore
 163 limited by the total physical memory on the system. It is also limited by the
 164 available kernel virtual address space, which is often the more restrictive
 165 constraint on large-memory configurations.
 166 .sp
 167 .LP
 168 Excessive use of kernel memory is likely to effect overall system performance.
 169 Over-commitment of kernel memory may cause unpredictable consequences.
 170 .sp
 171 .LP
 172 Misuse of the kernel memory allocator, such as writing past the end of a
 173 buffer, using a buffer after freeing it, freeing a buffer twice, or freeing an
 174 invalid pointer, will cause the system to corrupt data or panic.
 175 .sp
 176 .LP
 177 Do not call \fBddi_umem_alloc()\fR within \fBDDI_SUSPEND\fR and
 178 \fBDDI_RESUME\fR operations. Memory acquired at these times is not reliable. In
 179 some cases, such a call can cause a system to hang.
 180 .SH NOTES
 181 .sp
 182 .LP
 183 \fBddi_umem_alloc(0,\fR \fIflag\fR, \fIcookiep\fR\fB)\fR always returns
 184 \fBNULL.\fR \fBddi_umem_free(NULL)\fR has no effects on system.