ddi_check_dma_handle man page on Solaris

Man page or keyword search:  
man Server   20652 pages
apropos Keyword Search (all sections)
Output format
Solaris logo
[printable version]

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 simi‐
		       lar 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 spe‐
       cific type and returns a status value indicating whether faults affect‐
       ing 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	regis‐
       ters  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 ran‐
       dom 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 oper‐
       ation  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 han‐
       dle should be regarded as indeterminate.	 The fault indication  associ‐
       ated   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 communication 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, ®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);
	   }
	   ...

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)
[top]

List of man pages available for Solaris

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net