ddi_check_acc_handle(9F)				   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 <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() functions 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 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 asso-
       ciated 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 indication that a problem does exist with respect to com-
	       munication using that handle.

RETURN VALUES

       The  ddi_check_acc_handle() and ddi_check_dma_handle() functions 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() functions 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.10							  13 August 1999					  ddi_check_acc_handle(9F)