unmap(D2X)

NAME
     unmap - support virtual unmapping for memory-mapped device

SYNOPSIS
     #include <sys/types.h>
     #include <sys/mman.h>
     #include <sys/ddi.h>
     #include <ksys/ddmap.h>

     int prefixunmap(dev_t dev, vhandl_t *vt);

   Arguments
     dev  Device whose memory is to be mapped.

     vt   Handle to caller's virtual address space

DESCRIPTION
     To unmap a device, the user program calls munmap(2) system call.  After
     performing device-independent unmapping in the user's space, the munmap
     system call calls the driver's prefixunmap to remove the mapping.

   Return Values
     On success, 0 is returned. An error number is returned on failure.

USAGE
     If a driver provides a map(D2X) routine but does not provide an unmapping
     routine, the munmap system call returns the ENODEV error condition to the
     user.  Therefore, it is a good idea for all drivers to provide a dummy
     unmapping routine even if your driver does not need to perform any action
     to unmap the device.

   Synchronization Constraints
     The unmap routine has user context and can sleep.

     There are significant restrictions imposed on unmap routines that affect
     drivers that perform their own synchronization. When the unmap function
     is called, the address space for the process that is doing the call is
     locked. When an address space is locked, no other mapping or unmapping
     can take place and NO page faults can be serviced for the process. This
     can cause problems if the process is multi-threaded - one thread can be
     attempting to unmap the device and another thread can be accessing the
     driver through some other entry point (e.g. ioctl).  If the thread that
     is accessing the driver via ioctl locks a driver specific lock, and then
     calls e.g. copyin, and if the data to be copied in causes a page fault,
     then the page fault code will attempt to lock the address space lock. If,
     at the same time, another thread is attempting to unmap the device, and
     the unmap routine grabs the driver lock, an AB-BA deadlock can occur
     which will require re-booting the system to clear.  The safest way around
     this is to make sure that the driver never calls copyin or copyout while
     holding a driver lock and is used by the unmap routine.
REFERENCES
     map(D2X), v_getaddr(D3X), v_getlen(D3X), v_gethandle(D3X), v_mapphys(D3X)