kmem_alloc(D3)

NAME
     kmem_alloc - allocate space from kernel free memory

SYNOPSIS
     #include <sys/types.h>
     #include <sys/kmem.h>
     #include <sys/ddi.h>
     void *kmem_alloc(size_t size, int flag);

   Arguments
     size      Number of bytes to allocate.

     flag      Specifies whether the caller is willing to sleep waiting for
               memory, etc.

DESCRIPTION
     kmem_alloc allocates size bytes of kernel memory and returns a pointer to
     the allocated memory.  If flag is set to KM_SLEEP, the caller will sleep
     if necessary until the specified amount of memory is available.  If flag
     is set to KM_NOSLEEP, the caller will not sleep, but kmem_alloc will
     return NULL if the specified amount of memory is not immediately
     available. KM_PHYSCONTIG:  Allocate contiguous physical memory.

     CAUTION: It is best to call kmem_alloc with this flag only at driver
     initialization time. Otherwise, it may sleep for a very long time.

     KM_CACHEALIGN: 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 DMA must be cache-line aligned and padded to
     a full cache line.

   Return Values
     Upon successful completion, kmem_alloc returns a pointer to the allocated
     memory.  If KM_NOSLEEP is specified and sufficient memory is not
     immediately available, kmem_alloc returns a NULL pointer.  If size is set
     to 0, kmem_alloc returns NULL regardless of the value of flag.

USAGE
     Kernel memory is a limited resource and should be used judiciously.
     Memory allocated using kmem_alloc 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.

     Since holding memory allocated using kmem_alloc 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.
     The address returned by a successful call to kmem_alloc is word-aligned.

   Level
     Base only if flag is set to KM_SLEEP.

     Initialization, Base or Interrupt if flag is set to KM_NOSLEEP.

   Synchronization Constraints
     May sleep if flag is set to KM_SLEEP.

     Driver-defined basic locks and read/write locks may be held across calls
     to this function if flag is KM_NOSLEEP, but may not be held if flag is
     KM_SLEEP.

     Driver-defined sleep locks may be held across calls to this function
     regardless of the value of flag.

   Note
     kmem_alloc and kmem_free are intended as replacements for kmem_malloc and
     kern_free.  Drivers should use these routines rather than kern_malloc and
     kern_free.

REFERENCES
     kmem_free(D3), kmem_zalloc(D3), Appendix A, Section A.2, "Data cache
     Write Back and Invalidation" of the IRIX Device Driver Programming Guide