devmap_load(9F)

NAME

     devmap_unload, devmap_load - control  validation  of  memory
     address translations

SYNOPSIS

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

     int devmap_load(devmap_cookie_t dhp,  offset_t  off,  size_t
     len, uint_t type, uint_t rw);

     int devmap_unload(devmap_cookie_t dhp, offset_t off,  size_t
     len);

INTERFACE LEVEL

     Solaris DDI specific (Solaris DDI).

PARAMETERS

      dhp  An opaque mapping  handle  that  the  system  uses  to
           describe the mapping.

     off   User offset within the logical device memory at  which
           the  loading  or unloading of the address translations
           begins.

     len   Length (in bytes) of the range being affected.

  devmap_load() only
      type Type of access operation.

     rw    Direction of access.

DESCRIPTION

     devmap_unload() and devmap_load() are used  to  control  the
     validation  of  the  memory  mapping described by dhp in the
     specified range.  devmap_unload()  invalidates  the  mapping
     translations    and    will    generate    calls    to   the
     devmap_access(9E) entry  point  next  time  the  mapping  is
     accessed. The drivers use devmap_load() to validate the map-
     ping translations during memory access.

     A typical use of devmap_unload() and devmap_load() is in the
     driver's     context     management    callback    function,
     devmap_contextmgt(9E). To manage a device context, a  device
     driver  calls  devmap_unload()  on  the  context about to be
     switched  out.  It  switches  contexts,   and   then   calls
     devmap_load()  on the context switched in.   devmap_unload()
     can be used to unload the mappings  of  other  processes  as
     well   as   the   mappings   of  the  calling  process,  but
     devmap_load() can only be used to load the mappings  of  the
     calling  process.  Attempting to load another process's map-
     pings with devmap_load() will result in a system panic.
     For both routines, the range to be affected  is  defined  by
     the  off  and len arguments. Requests affect the entire page
     containing the off and all pages up  to  and  including  the
     page containing the last byte as indicated by off + len. The
     arguments type and rw are provided by the system to the cal-
     ling   function  (for  example,  devmap_contextmgt(9E))  and
     should not be modified.

     Supplying a value of  0 for the  len  argument  affects  all
     addresses from the off to the end of the mapping.  Supplying
     a value of 0 for the off argument and a value of 0  for  len
     argument affect all addresses in the mapping.

     A non-zero  return  value  from  either  devmap_unload()  or
     devmap_load()  will  cause  the  corresponding  operation to
     fail. The failure may result in a SIGSEGV or  SIGBUS  signal
     being delivered to the process.

RETURN VALUES

      0    Successful completion.

     Non-zero
           An error occurred.

CONTEXT

     These routines can be called from  user  or  kernel  context
     only.

EXAMPLES

     Example 1: Managing a One-Page Device Context

     The following shows an example of managing a device  context
     that is one page in length.

     struct xx_context cur_ctx;

     static int
     xxdevmap_contextmgt(devmap_cookie_t dhp, void *pvtp, offset_t off,
        size_t len, uint_t type, uint_t rw)
     {
         int err;
         devmap_cookie_t cur_dhp;
         struct xx_pvt *p;
         struct xx_pvt *pvp = (struct xx_pvt *)pvtp;
         /* enable access callbacks for the current mapping */
         if (cur_ctx != NULL && cur_ctx != pvp->ctx) {
             p = cur_ctx->pvt;
             /*
              * unload the region from off to the end of the mapping.
              */
             cur_dhp = p->dhp;
             if ((err = devmap_unload(cur_dhp, off, len)) != 0)
                 return (err);
         }
         /* Switch device context - device dependent*/
         ...
         /* Make handle the new current mapping */
         cur_ctx = pvp->ctx;
         /*
          * Disable callbacks and complete the access for the
          * mapping that generated this callback.
          */
         return (devmap_load(pvp->dhp, off, len, type, rw));
     }

SEE ALSO

     devmap_access(9E), devmap_contextmgt(9E)

     Writing Device Drivers