ddi_umem_lock(9F)

NAME

     ddi_umem_lock, ddi_umem_unlock  -  lock  and  unlock  memory
     pages

SYNOPSIS

     #include <sys/ddi.h>
     #include <sys/sunddi.h>

     int  ddi_umem_lock(caddr_t  addr,  size_t  len,  int  flags,
     ddi_umem_cookie_t *cookiep);

     void ddi_umem_unlock(ddi_umem_cookie_t cookie);

INTERFACE LEVEL

     Solaris DDI specific (Solaris DDI)

PARAMETERS

  ddi_umem_lock
     addr  Virtual address of memory object

     len   Length of memory object in bytes

     flags Valid flags include:

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

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

     cookiep
           Pointer to a kernel memory cookie.

  ddi_umem_unlock
     cookie
           Kernel memory cookie allocated by ddi_umem_lock().

DESCRIPTION

     The ddi_umem_lock(9F) 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  per-
     form       I/O       (see      ddi_umem_iosetup(9F)      and
     ddi_dma_buf_bind_handle(9F)),  or  it  can  be   used   with
     devmap_umem_setup(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 DDI_UMEMLOCK_READ if the memory pages
     will be read (for example, in a  disk  write  or  a  network
     send.)  Set  flags to DDI_UMEMLOCK_WRITE 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
     ddi_umem_unlock(9F)    with   the   cookie   obtained   from
     ddi_umem_lock(9F).

     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

     EACCES
           User process does not have the required permission.

     ENOMEM
           The system does not have sufficient resources to  lock
           memory.

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

     EINVAL
           Requested memory is not aligned on a system page boun-
           dary.

CONTEXT

     The ddi_umem_lock() function can only be  called  from  user
     context;  ddi_umem_unlock() from user, kernel, and interrupt
     contexts.

SEE ALSO

     ddi_umem_iosetup(9F),           ddi_dma_buf_bind_handle(9F),
     devmap_umem_setup(9F), ddi_umem_alloc(9F)

NOTES

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

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