Kernel Functions for Drivers             ddicheckacchandle(9F)



NAME
     ddicheckacchandle,  ddicheckdmahandle  -  Check   data
     access and DMA handles

SYNOPSIS
     #include 
     #include 



     int ddicheckacchandle(ddiacchandlet  acchandle );


     int ddicheckdmahandle(ddidmahandlet  dmahandle );


INTERFACE LEVEL
     Solaris DI specific (Solaris DI)

PARAMETERS
     acchandle     Data access handle obtained from  a  previous
                    call        to        ddiregsmapsetup(9F),
                    ddidmamemalloc(9F), or similar function.


     dmahandle     DMA handle obtained from a previous  call  to
                    ddidmasetup(9F) or one of its derivatives.


DESCRIPTION
     The ddicheckacchandle() and ddicheckdmahandle()  func-
     tions check for faults that can interfere with communication
     between a driver and the device it controls.  Each  function
     checks  a  single  handle  of  a specific type and returns a
     status  value  indicating  whether  faults   affecting   the
     resource mapped by the supplied handle have been detected.


     If a fault is indicated when checking a data access  handle,
     this implies that the driver is no longer able to access the
     mapped registers or memory using programmed I/O through that
     handle.   Typically,  this  might occur after the device has
     failed to  respond  to  an  I/O  access  (for  example,  has
     incurred a bus error or timed out). The effect of programmed
     I/O accesses made after this happens is undefined; for exam-
     ple,  read  accesses  (for example, ddiget8(9F)) may return
     random   values,   and   write   accesses   (for    example,
     ddiput8(9F))  may  or may not have any effect. This type of
     fault is normally fatal to the operation of the device,  and
     the  driver  should  report  it via ddidevreportfault(9F)
     specifying   DISERVICELOST   for    the    impact,    and
     DIDATAPATHFAULT for the location.



SunOS 5.11         Last change: 13 August 1999                  1






Kernel Functions for Drivers             ddicheckacchandle(9F)



     If a fault is indicated  when  checking  a  DMA  handle,  it
     implies  that  a  fault has been detected that has (or will)
     affect DMA transactions between the device  and  the  memory
     currently  bound  to  the handle (or most recently bound, if
     the handle is currently unbound).  Possible  causes  include
     the  failure  of  a  component  in  the DMA data path, or an
     attempt by the device to make an  invalid  DMA  access.  The
     driver  may be able to continue by falling back to a non-DMA
     mode of operation, but  in  general,  DMA  faults  are  non-
     recoverable.   The contents of the memory currently (or pre-
     viously) bound to the handle should be regarded as  indeter-
     minate.  The  fault  indication  associated with the current
     transaction is lost  once  the  handle  is  (re-)bound,  but
     because the fault may persist, future DMA operations may not
     succeed.


     Note that some implementations cannot detect  all  types  of
     failure.  If a fault is not indicated, this does not consti-
     tute a guarantee that communication is possible. However, if
     a  check fails, this is a positive indication that a problem
     does exist with respect to communication using that handle.

RETURN VALUES
     The ddicheckacchandle() and ddicheckdmahandle()  func-
     tions return DISUCES if no faults affecting the supplied
     handle are detected and DIFAILURE if any  fault  affecting
     the supplied handle is detected.

EXAMPLES
       static int
       xxattach(devinfot *dip, ddiattachcmdt cmd)
       {
           ...
           /* This driver uses only a single register-access handle */
           status = ddiregsmapsetup(dip, REGSETZERO, ®addr,
                                       0, 0, , &accattrs, &acchdl);
           if (status != DISUCES)
               return (DIFAILURE);
           ...
       }

       static int
       xxread(devt  dev, struct uio *uiop, credt *credp)
       {
           ...
           if (ddicheckacchandle(acchdl) != DISUCES) {
               ddidevreportfault(dip, DISERVICELOST,
                   DIDATAPATHFAULT, "register access fault during read");
               return (EIO);
           }
           ...



SunOS 5.11         Last change: 13 August 1999                  2






Kernel Functions for Drivers             ddicheckacchandle(9F)



CONTEXT
     The ddicheckacchandle() and ddicheckdmahandle()  func-
     tions may be called from user, kernel, or interrupt context.

SEE ALSO
     ddiregsmapsetup(9F),                   ddidmasetup(9F),
     ddidevreportfault(9F), ddiget8(9F), ddiput8(9F)
















































SunOS 5.11         Last change: 13 August 1999                  3