Manual Pages for UNIX Operating System command usage for man ddi_check_acc_handle

Kernel Functions for Drivers             ddi_check_acc_handle(9F)



NAME
     ddi_check_acc_handle,  ddi_check_dma_handle  -  Check   data
     access and DMA handles

SYNOPSIS
     #include 
     #include 



     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 programmed
     I/O accesses made after this happens is undefined; for exam-
     ple,  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.



SunOS 5.11         Last change: 13 August 1999                  1






Kernel Functions for Drivers             ddi_check_acc_handle(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 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, ®addr,
                                       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);
           }
           ...



SunOS 5.11         Last change: 13 August 1999                  2






Kernel Functions for Drivers             ddi_check_acc_handle(9F)



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)
















































SunOS 5.11         Last change: 13 August 1999                  3