Manual Pages for UNIX Operating System command usage for man devmap_access

Driver Entry Points                             devmap_access(9E)



NAME
     devmap_access - device mapping access entry point

SYNOPSIS
     #include 
     #include 



     int prefixdevmap_access(devmap_cookie_t dhp, void *pvtp,
          offset_t off, size_t len, uint_t type, uint_t rw);


INTERFACE LEVEL
     Solaris DDI specific (Solaris DDI).

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


     pvtp     Driver private mapping data.


     off      User offset within the  logical  device  memory  at
              which the access begins.


     len      Length (in bytes) of the memory being accessed.


     type     Type of access operation.  Possible values are:

              DEVMAP_ACCESS     Memory access.


              DEVMAP_LOCK       Lock the memory being accessed.


              DEVMAP_UNLOCK     Unlock the memory being accessed.



     rw       Direction of access.  Possible values are:

              DEVMAP_READ      Read access attempted.


              DEVMAP_WRITE     Write access attempted.






SunOS 5.11          Last change: 17 Jan 1997                    1






Driver Entry Points                             devmap_access(9E)



              DEVMAP_EXEC      Execution access attempted.



DESCRIPTION
     The devmap_access() entry point is an optional routine.   It
     notifies  drivers  whenever  an  access is made to a mapping
     described by  dhp that has not been validated or  does   not
     have  sufficient  protection  for  the  access.   The system
     expects devmap_access() to call either  devmap_do_ctxmgt(9F)
     or  devmap_default_access(9F)  to  load  the  memory address
     translations before it returns. For  mappings  that  support
     context    switching,     device    drivers    should   call
     devmap_do_ctxmgt(9F). For mappings that do not support  con-
     text      switching,     the     drivers     should     call
     devmap_default_access(9F).


     In  devmap_access(), drivers perform memory  access  related
     operations  such  as context switching, checking the availa-
     bility of the memory  object, and locking and unlocking  the
     memory  object  being  accessed.  The  devmap_access() entry
     point is set to  NULL if no operations need to be performed.


     pvtp is a pointer to the driver's private mapping data  that
     was  allocated  and  initialized in the devmap_map(9E) entry
     point.


     off and len define the range to be affected  by  the  opera-
     tions in devmap_access(). type defines the type of operation
     that device drivers should perform on the memory object.  If
     type  is  either  DEVMAP_LOCK  or  DEVMAP_UNLOCK, the length
     passed      to      either      devmap_do_ctxmgt(9F)      or
     devmap_default_access(9F) must be same as  len. rw specifies
     the direction of access on the memory object.


     A non-zero return value from  devmap_access() may result  in
     a SIGSEGV or SIGBUS signal being delivered to the process.

RETURN VALUES
     devmap_access() returns the following values:

     0           Successful completion.


     Non-zero    An  error  occurred.   The  return  value   from
                 devmap_do_ctxmgt(9F)                          or
                 devmap_default_access(9F) should be returned.




SunOS 5.11          Last change: 17 Jan 1997                    2






Driver Entry Points                             devmap_access(9E)



EXAMPLES
     Example 1 devmap_access() entry point


     The following is an example  of  the  devmap_access()  entry
     point.    If   the   mapping   supports  context  switching,
     devmap_access()   calls   devmap_do_ctxmgt(9F).   Otherwise,
     devmap_access() calls devmap_default_access(9F).


       ...
       #define OFF_DO_CTXMGT  0x40000000
       #define OFF_NORMAL     0x40100000
       #define CTXMGT_SIZE    0x100000
       #define NORMAL_SIZE    0x100000

       /*
        * Driver devmap_contextmgt(9E) callback function.
        */
       static int
       xx_context_mgt(devmap_cookie_t dhp, void *pvtp, offset_t offset,
          size_t length, uint_t type, uint_t rw)
       {
          ......
          /*
           * see devmap_contextmgt(9E) for an example
           */
       }

       /*
        * Driver devmap_access(9E) entry point
        */
       static int
       xxdevmap_access(devmap_cookie_t dhp, void *pvtp, offset_t off,
          size_t len, uint_t type, uint_t rw)
       {
          offset_t diff;
          int err;

          /*
           * check if off is within the range that supports
           * context management.
           */
          if ((diff = off - OFF_DO_CTXMG) >= 0 && diff < CTXMGT_SIZE) {
              /*
               * calculates the length for context switching
               */
              if ((len + off) > (OFF_DO_CTXMGT + CTXMGT_SIZE))
                  return (-1);
              /*
               * perform context switching
               */



SunOS 5.11          Last change: 17 Jan 1997                    3






Driver Entry Points                             devmap_access(9E)



              err = devmap_do_ctxmgt(dhp, pvtp, off, len, type,
                  rw, xx_context_mgt);
           /*
            * check if  off is within the range that does normal
            * memory mapping.
            */
           } else if ((diff = off - OFF_NORMAL) >= 0 && diff < NORMAL_SIZE) {
              if ((len + off) > (OFF_NORMAL + NORMAL_SIZE))
                  return (-1);
              err = devmap_default_access(dhp, pvtp, off, len, type, rw);
           } else
              return (-1);

          return (err);
       }


SEE ALSO
     devmap_map(9E),                   devmap_default_access(9F),
     devmap_do_ctxmgt(9F), devmap_callback_ctl(9S)


     Writing Device Drivers
































SunOS 5.11          Last change: 17 Jan 1997                    4