Kernel Functions for Drivers                    ddiumemlock(9F)



NAME
     ddiumemlock, ddiumemunlock  -  lock  and  unlock  memory
     pages

SYNOPSIS
     #include 
     #include 

     int ddiumemlock(caddrt addr, sizet len, int flags,
          ddiumemcookiet *cookiep);


     void ddiumemunlock(ddiumemcookiet cookie);


INTERFACE LEVEL
     Solaris DI specific (Solaris DI)

PARAMETERS
  ddiumemlock
     addr       Virtual address of memory object


     len        Length of memory object in bytes


     flags      Valid flags include:

                DIUMEMLOCKREAD    Memory pages are  locked  to
                                     be read from. (Disk write or
                                     a network send.)


                DIUMEMLOCKWRITE    Memory pages are locked  to
                                      be  written  to. (Disk read
                                      or a network receive.)



     cookiep    Pointer to a kernel memory cookie.


  ddiumemunlock
     cookie    Kernel memory cookie allocated by ddiumemlock().


DESCRIPTION
     The ddiumemlock() function locks down the  physical  pages
     (including  I/O  pages)  that correspond to the current pro-
     cess' virtual address range [addr, addr ] size) and fills in
     a  cookie  representing the locked pages. This cookie can be
     used to create a buf(9S)  structure  that  can  be  used  to



SunOS 5.11          Last change: 10 Apr 2007                    1






Kernel Functions for Drivers                    ddiumemlock(9F)



     perform      I/O      (see      ddiumemiosetup(9F)     and
     ddidmabufbindhandle(9F),  or  it  can   be   used   with
     devmapumemsetup(9F)  to  export  the memory to an applica-
     tion.


     The virtual address and length specified must be at  a  page
     boundary  and  the  mapping performed in terms of the system
     page size. See pagesize(1).


     The flags argument indicates the intended use of the  locked
     memory.  Set  flags to DIUMEMLOCKREAD if the memory pages
     will be read (for example, in a  disk  write  or  a  network
     send.)  Set  flags to DIUMEMLOCKWRITE if the memory pages
     will be written (for example, in a disk read  or  a  network
     receive).  You  must  choose  one  (and  only  one) of these
     values.


     To   unlock   the   locked   pages,   the    drivers    call
     ddiumemunlock(9F)    with   the   cookie   obtained   from
     ddiumemlock().


     The process is not allowed to exec(2) or fork(2)  while  its
     physical pages are locked down by the device driver.


     The device driver must ensure that the physical  pages  have
     been unlocked after the application has called close(2).

RETURN VALUES
     On success, a 0 is returned. Otherwise, one of the following
     errno values is returned.

     EFAULT    User process has no mapping at that address  range
               or does not support locking


     EACES    User process does not have  the  required  permis-
               sion.


     ENOMEM    The system does not have sufficient  resources  to
               lock  memory, or locking len memory would exceed a
               limit or resource control on locked memory.


     EAGAIN    Could not allocate system  resources  required  to
               lock  the pages. The ddiumemlock() could succeed
               at a later time.



SunOS 5.11          Last change: 10 Apr 2007                    2






Kernel Functions for Drivers                    ddiumemlock(9F)



     EINVAL    Requested memory is not aligned on a  system  page
               boundary.


CONTEXT
     The ddiumemlock() function can only be  called  from  user
     context;  ddiumemunlock() from user, kernel, and interrupt
     contexts.

SEE ALSO
     ddiumemiosetup(9F),           ddidmabufbindhandle(9F),
     devmapumemsetup(9F), ddiumemalloc(9F)

NOTES
     The ddiumemunlock() function consumes physical memory. The
     driver  is  responsible  for  a speedy unlock to free up the
     resources.


     The ddiumemunlock() function can defer  unlocking  of  the
     pages to a later time depending on the implementation.


































SunOS 5.11          Last change: 10 Apr 2007                    3