Kernel Functions for Drivers                   ddiumemalloc(9F)



NAME
     ddiumemalloc, ddiumemfree  -  allocate  and  free  page-
     aligned kernel memory

SYNOPSIS
     #include 
     #include 

     void *ddiumemalloc(sizet size, int flag,
          ddiumemcookiet *cookiep);


     void ddiumemfree(ddiumemcookiet cookie);


INTERFACE LEVEL
     Solaris DI specific (Solaris DI).

PARAMETERS
  ddiumemalloc()
     size       Number of bytes to allocate.


     flag       Used to determine the sleep and  pageable  condi-
                tions.

                Possible sleep flags  are  DIUMEMSLEP,  which
                allows  sleeping  until  memory is available, and
                DIUMEMNOSLEP, which returns NUL  immediately
                if memory is not available.

                The  default  condition  is  to  allocate  locked
                memory;  this can be changed to allocate pageable
                memory using the DIUMEMPAGEABLE flag.


     cookiep    Pointer to a kernel memory cookie.


  ddiumemfree()
     cookie    A    kernel    memory    cookie    allocated    in
               ddiumemalloc().


DESCRIPTION
     ddiumemalloc() allocates page-aligned  kernel  memory  and
     returns  a  pointer  to  the allocated memory. The number of
     bytes allocated is  a  multiple  of  the  system  page  size
     (roundup  of  size). The allocated memory can be used in the
     kernel and can be exported to user space. See devmap(9E) and
     devmapumemsetup(9F) for further information.




SunOS 5.11          Last change: 19 Mar 2002                    1






Kernel Functions for Drivers                   ddiumemalloc(9F)



     flag determines whether the caller can sleep for memory  and
     whether   the   allocated   memory   is   locked   or   not.
     DIUMEMSLEP allocations may sleep but are  guaranteed  to
     succeed.  DIUMEMNOSLEP  allocations do not sleep but may
     fail (return NUL) if memory is  currently  unavailable.  If
     DIUMEMPAGEABLE is set, pageable memory will be allocated.
     These pages can be swapped out to secondary memory  devices.
     The    initial    contents   of   memory   allocated   using
     ddiumemalloc() is zero-filled.


     *cookiep is a pointer  to  the  kernel  memory  cookie  that
     describes  the  kernel memory being allocated. A typical use
     of cookiep is in devmapumemsetup(9F) when the drivers want
     to export the kernel memory to a user application.


     To free the allocated memory, a driver calls ddiumemfree()
     with    the    cookie    obtained   from   ddiumemalloc().
     ddiumemfree() releases the entire buffer.

RETURN VALUES
     Non-null    Successful completion. ddiumemalloc()  returns
                 a pointer to the allocated memory.


     NUL        Memory cannot be allocated  by  ddiumemalloc()
                 because  DIUMEMNOSLEP  is set and the system
                 is out of resources.


CONTEXT
     ddiumemalloc() can be called from any context if  flag  is
     set   to   DIUMEMNOSLEP.   If   DIUMEMSLEP  is  set,
     ddiumemalloc() can be called from user and kernel  context
     only. ddiumemfree() can be called from any context.

SEE ALSO
     devmap(9E),       condvar(9F),        devmapumemsetup(9F),
     kmemalloc(9F), mutex(9F), rwlock(9F), semaphore(9F)


     Writing Device Drivers

WARNINGS
     Setting the DIUMEMPAGEABLE flag in ddiumemalloc()  will
     result  in  an  allocation of pageable memory. Because these
     pages can  be  swapped  out  to  secondary  memory  devices,
     drivers should use this flag with care. This memory must not
     be used for the following purposes:

         o    For  synchronization  objects  such  as  locks  and



SunOS 5.11          Last change: 19 Mar 2002                    2






Kernel Functions for Drivers                   ddiumemalloc(9F)



              condition  variables. See mutex(9F), semaphore(9F),
              rwlock(9F), and condvar(9F).

         o    For driver interrupt routines.


     Memory  allocated  using  ddiumemalloc()  without  setting
     DIUMEMPAGEABLE  flag cannot be paged. Available memory is
     therefore limited by the total physical memory on  the  sys-
     tem.  It  is  also  limited  by the available kernel virtual
     address space, which is  often  the  more  restrictive  con-
     straint on large-memory configurations.


     Excessive use of kernel memory is likely to  effect  overall
     system  performance.  Over-commitment  of  kernel memory may
     cause unpredictable consequences.


     Misuse of the kernel memory allocator, such as writing  past
     the  end of a buffer, using a buffer after freeing it, free-
     ing a buffer twice, or  freeing  an  invalid  pointer,  will
     cause the system to corrupt data or panic.


     Do  not  call  ddiumemalloc()   within   DISUSPEND   and
     DIRESUME operations. Memory acquired at these times is not
     reliable. In some cases, such a call can cause a  system  to
     hang.

NOTES
     ddiumemalloc(0,  flag,  cookiep)  always   returns   NUL.
     ddiumemfree(NUL) has no effects on system.






















SunOS 5.11          Last change: 19 Mar 2002                    3