ddi_check_acc_handle(9F)

NAME

     ddi_check_acc_handle,  ddi_check_dma_handle  -  Check   data
     access and DMA handles

SYNOPSIS

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

     int ddi_check_acc_handle(ddi_acc_handle_t  acc_handle );

     int ddi_check_dma_handle(ddi_dma_handle_t  dma_handle );

INTERFACE LEVEL

     Solaris DDI specific (Solaris DDI)

PARAMETERS

     acc_handle
           Data access handle obtained from a  previous  call  to
           ddi_regs_map_setup(9F),    ddi_dma_mem_alloc(9F),   or
           similar function.

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

DESCRIPTION

     The ddi_check_acc_handle() and ddi_check_dma_handle()  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 pro-
     grammed I/O accesses made after this happens  is  undefined;
     for  example,  read accesses (for example, ddi_get8(9F)) may
     return random  values,  and  write  accesses  (for  example,
     ddi_put8(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 ddi_dev_report_fault(9F)
     specifying   DDI_SERVICE_LOST   for    the    impact,    and
     DDI_DATAPATH_FAULT for the location.

     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 previously)  bound
     to  the  handle  should  be  regarded as indeterminate.  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:

          Some  implementations  cannot  detect  all   types   of
          failure.     If a fault is not indicated, this does not
          constitute a guarantee that communication is  possible.
          However,  if  a check fails, this is a positive indica-
          tion that a problem does exist with respect to communi-
          cation using that handle.

RETURN VALUES

     The ddi_check_acc_handle() and ddi_check_dma_handle()  func-
     tions return DDI_SUCCESS if no faults affecting the supplied
     handle are detected and DDI_FAILURE if any  fault  affecting
     the supplied handle is detected.

EXAMPLES

     static int
     xxattach(dev_info_t *dip, ddi_attach_cmd_t cmd)
     {
         ...
         /* This driver uses only a single register-access handle */
         status = ddi_regs_map_setup(dip, REGSET_ZERO, &regaddr,
                                     0, 0, , &acc_attrs, &acc_hdl);
         if (status != DDI_SUCCESS)
             return (DDI_FAILURE);
         ...
     }

     static int
     xxread(dev_t  dev, struct uio *uio_p, cred_t *cred_p)
     {
         ...
         if (ddi_check_acc_handle(acc_hdl) != DDI_SUCCESS) {
             ddi_dev_report_fault(dip, DDI_SERVICE_LOST,
                 DDI_DATAPATH_FAULT, "register access fault during read");
             return (EIO);
         }
         ...

CONTEXT

     The ddi_check_acc_handle() and ddi_check_dma_handle()  func-
     tions may be called from user, kernel, or interrupt context.

SEE ALSO

     ddi_regs_map_setup(9F),                   ddi_dma_setup(9F),
     ddi_dev_report_fault(9F), ddi_get8(9F), ddi_put8(9F)