97 lines
3.3 KiB
Plaintext
97 lines
3.3 KiB
Plaintext
.if n .pH ddi.rm/d3/gen/kmem_alloc @(#)kmem_alloc 43.13 of 12/7/92
|
|
.\" Copyright 1992, 1991 UNIX System Laboratories, Inc.
|
|
.TH kmem_alloc D3
|
|
.SH NAME
|
|
\f4kmem_alloc\f1 \- allocate space from kernel free memory
|
|
.IX "\f4kmem_alloc\fP(D3)"
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.na
|
|
.ft 4
|
|
#include <sys/types.h>
|
|
#include <sys/kmem.h>
|
|
#include <sys/ddi.h>
|
|
.sp 0.4
|
|
void *kmem_alloc(size_t \f2size\fP, int \f2flag\fP);
|
|
.ft 1
|
|
.ad
|
|
.fi
|
|
.SS Arguments
|
|
.RS 0
|
|
.IP "\f2size\f1" 10n
|
|
Number of bytes to allocate.
|
|
.IP "\f2flag\f1" 10n
|
|
Specifies whether the caller is willing to sleep waiting for memory, etc.
|
|
.RE
|
|
.SH DESCRIPTION
|
|
\f4kmem_alloc\f1 allocates \f2size\f1 bytes of kernel
|
|
memory and returns a pointer to the allocated memory.
|
|
If \f2flag\f1 is set to \f4KM_SLEEP\f1, the caller will sleep
|
|
if necessary until the specified amount of memory is available.
|
|
If \f2flag\f1 is set to \f4KM_NOSLEEP\f1, the caller will not sleep,
|
|
but \f4kmem_alloc\f1 will return \f4NULL\f1 if the specified amount
|
|
of memory is not immediately available. \f4KM_PHYSCONTIG\f1:
|
|
Allocate contiguous physical memory.
|
|
.P
|
|
\f4CAUTION:\fP It is best to call \f4kmem_alloc\f1 with this flag
|
|
\f2only\f1 at driver initialization time. Otherwise, it may
|
|
sleep for a very long time.
|
|
.P
|
|
\f4KM_CACHEALIGN:\fP Allocate the requested memory starting
|
|
at a cache line boundary. This also pads the buffer out to a
|
|
full cache line. Buffers that the driver will use for
|
|
\f4DMA\f1 must be cache-line aligned and padded to a full
|
|
cache line.
|
|
.SS "Return Values"
|
|
Upon successful completion, \f4kmem_alloc\f1 returns a pointer to the
|
|
allocated memory.
|
|
If \f4KM_NOSLEEP\f1 is specified and sufficient memory is not immediately
|
|
available, \f4kmem_alloc\f1 returns a \f4NULL\f1 pointer.
|
|
If \f2size\f1 is set to \f40\f1, \f4kmem_alloc\f1 returns \f4NULL\f1
|
|
regardless of the value of \f2flag\f1.
|
|
.SH USAGE
|
|
Kernel memory is a limited resource and should be used judiciously.
|
|
Memory allocated using \f4kmem_alloc\f1 should be freed as soon as
|
|
possible.
|
|
Drivers should not use local freelists for memory or similar schemes
|
|
that cause the memory to be held for longer than necessary.
|
|
.P
|
|
Since holding memory allocated using \f4kmem_alloc\f1 for extended periods
|
|
of time (e.g allocating memory at system startup and never freeing it)
|
|
can have an adverse effect on overall memory usage and system performance,
|
|
memory needed for such extended periods should be statically allocated whenever
|
|
possible.
|
|
.P
|
|
The address returned by a successful call to \f4kmem_alloc\f1 is
|
|
word-aligned.
|
|
.SS Level
|
|
Base only if \f2flag\f1 is set to \f4KM_SLEEP\f1.
|
|
.P
|
|
Initialization, Base or Interrupt if \f2flag\f1 is set to \f4KM_NOSLEEP\f1.
|
|
.SS "Synchronization Constraints"
|
|
May sleep if \f2flag\f1 is set to \f4KM_SLEEP\f1.
|
|
.P
|
|
Driver-defined basic locks and read/write locks
|
|
may be held across calls to this function
|
|
if \f2flag\f1 is \f4KM_NOSLEEP\f1,
|
|
but may not be held if \f2flag\f1 is \f4KM_SLEEP\f1.
|
|
.P
|
|
Driver-defined sleep locks
|
|
may be held across calls to this function
|
|
regardless of the value of \f2flag\f1.
|
|
.SS Note
|
|
\f4kmem_alloc\fP and \f4kmem_free\fP are intended as
|
|
replacements for \f4kmem_malloc\fP and \f4kern_free\fP.
|
|
Drivers should use these routines rather than \f4kern_malloc\fP
|
|
and \f4kern_free\fP.
|
|
.SH REFERENCES
|
|
.na
|
|
\f4kmem_free\fP(D3),
|
|
\f4kmem_zalloc\fP(D3),
|
|
Appendix A, Section A.2, "Data cache Write Back and
|
|
Invalidation" of the \f2
|
|
.xref DevDriver_PG 65886
|
|
IRIX Device Driver Programming Guide
|
|
\fP
|
|
.ad
|