1 '\" te

   2 .\"  Copyright (c) 1999, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH DDI_CHECK_ACC_HANDLE 9F "Aug 13, 1999"
   7 .SH NAME
   8 ddi_check_acc_handle, ddi_check_dma_handle \- Check data access and DMA handles
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/ddi.h>
  13 #include <sys/sunddi.h>
  14 
  15 
  16 
  17 \fBint\fR \fBddi_check_acc_handle\fR(\fBddi_acc_handle_t\fR \fI acc_handle\fR );
  18 .fi
  19 
  20 .LP
  21 .nf
  22 \fBint\fR \fBddi_check_dma_handle\fR(\fBddi_dma_handle_t\fR  \fIdma_handle\fR );
  23 .fi
  24 
  25 .SH INTERFACE LEVEL
  26 .sp
  27 .LP
  28 Solaris DDI specific (Solaris DDI)
  29 .SH PARAMETERS
  30 .sp
  31 .ne 2
  32 .na
  33 \fB\fIacc_handle\fR \fR
  34 .ad
  35 .RS 15n
  36 Data access handle obtained from a previous call to
  37 \fBddi_regs_map_setup\fR(9F), \fBddi_dma_mem_alloc\fR(9F), or similar function.
  38 .RE
  39 
  40 .sp
  41 .ne 2
  42 .na
  43 \fB\fIdma_handle\fR \fR
  44 .ad
  45 .RS 15n
  46 DMA handle obtained from a previous call to \fBddi_dma_setup\fR(9F) or one of
  47 its derivatives.
  48 .RE
  49 
  50 .SH DESCRIPTION
  51 .sp
  52 .LP
  53 The \fBddi_check_acc_handle()\fR\fB and ddi_check_dma_handle()\fR functions
  54 check for faults that can interfere with communication between a driver and the
  55 device it controls. Each function checks a single handle of a specific type and
  56 returns a status value indicating whether faults affecting the resource mapped
  57 by the supplied handle have been detected.
  58 .sp
  59 .LP
  60 If a fault is indicated when checking a data access handle, this implies that
  61 the driver is no longer able to access the mapped registers or memory using
  62 programmed I/O through that handle.  Typically, this might occur after the
  63 device has failed to respond to an I/O access (for example, has incurred a bus
  64 error or timed out). The effect of programmed I/O accesses made after this
  65 happens is undefined; for example, read accesses (for example,
  66 \fBddi_get8\fR(9F)) may return random values, and write accesses (for example,
  67 \fBddi_put8\fR(9F)) may or may not have any effect. This type of fault is

 114 xxread(dev_t  dev, struct uio *uio_p, cred_t *cred_p)
 115 {
 116     \&...
 117     if (ddi_check_acc_handle(acc_hdl) != DDI_SUCCESS) {
 118         ddi_dev_report_fault(dip, DDI_SERVICE_LOST,
 119             DDI_DATAPATH_FAULT, "register access fault during read");
 120         return (EIO);
 121     }
 122     \&...
 123 .fi
 124 .in -2
 125 
 126 .SH CONTEXT
 127 .sp
 128 .LP
 129 The \fBddi_check_acc_handle()\fR and \fBddi_check_dma_handle()\fR functions may
 130 be called from user, kernel, or interrupt context.
 131 .SH SEE ALSO
 132 .sp
 133 .LP
 134 \fBddi_regs_map_setup\fR(9F), \fBddi_dma_setup\fR(9F),
 135 \fBddi_dev_report_fault\fR(9F), \fBddi_get8\fR(9F), \fBddi_put8\fR(9F)

   1 '\" te
   2 .\"  Copyright 2014 Garrett D'Amore <garrett@damore.org>
   3 .\"  Copyright (c) 1999, Sun Microsystems, Inc.  All Rights Reserved
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH DDI_CHECK_ACC_HANDLE 9F "May 24, 2014"
   8 .SH NAME
   9 ddi_check_acc_handle, ddi_check_dma_handle \- Check data access and DMA handles
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/ddi.h>
  14 #include <sys/sunddi.h>
  15 
  16 
  17 
  18 \fBint\fR \fBddi_check_acc_handle\fR(\fBddi_acc_handle_t\fR \fI acc_handle\fR );
  19 .fi
  20 
  21 .LP
  22 .nf
  23 \fBint\fR \fBddi_check_dma_handle\fR(\fBddi_dma_handle_t\fR  \fIdma_handle\fR );
  24 .fi
  25 
  26 .SH INTERFACE LEVEL
  27 .sp
  28 .LP
  29 Solaris DDI specific (Solaris DDI)
  30 .SH PARAMETERS
  31 .sp
  32 .ne 2
  33 .na
  34 \fB\fIacc_handle\fR \fR
  35 .ad
  36 .RS 15n
  37 Data access handle obtained from a previous call to
  38 \fBddi_regs_map_setup\fR(9F), \fBddi_dma_mem_alloc\fR(9F), or similar function.
  39 .RE
  40 
  41 .sp
  42 .ne 2
  43 .na
  44 \fB\fIdma_handle\fR \fR
  45 .ad
  46 .RS 15n
  47 DMA handle obtained from \fBddi_dma_alloc_handle\fP(9F).

  48 .RE
  49 
  50 .SH DESCRIPTION
  51 .sp
  52 .LP
  53 The \fBddi_check_acc_handle()\fR\fB and ddi_check_dma_handle()\fR functions
  54 check for faults that can interfere with communication between a driver and the
  55 device it controls. Each function checks a single handle of a specific type and
  56 returns a status value indicating whether faults affecting the resource mapped
  57 by the supplied handle have been detected.
  58 .sp
  59 .LP
  60 If a fault is indicated when checking a data access handle, this implies that
  61 the driver is no longer able to access the mapped registers or memory using
  62 programmed I/O through that handle.  Typically, this might occur after the
  63 device has failed to respond to an I/O access (for example, has incurred a bus
  64 error or timed out). The effect of programmed I/O accesses made after this
  65 happens is undefined; for example, read accesses (for example,
  66 \fBddi_get8\fR(9F)) may return random values, and write accesses (for example,
  67 \fBddi_put8\fR(9F)) may or may not have any effect. This type of fault is

 114 xxread(dev_t  dev, struct uio *uio_p, cred_t *cred_p)
 115 {
 116     \&...
 117     if (ddi_check_acc_handle(acc_hdl) != DDI_SUCCESS) {
 118         ddi_dev_report_fault(dip, DDI_SERVICE_LOST,
 119             DDI_DATAPATH_FAULT, "register access fault during read");
 120         return (EIO);
 121     }
 122     \&...
 123 .fi
 124 .in -2
 125 
 126 .SH CONTEXT
 127 .sp
 128 .LP
 129 The \fBddi_check_acc_handle()\fR and \fBddi_check_dma_handle()\fR functions may
 130 be called from user, kernel, or interrupt context.
 131 .SH SEE ALSO
 132 .sp
 133 .LP
 134 \fBddi_regs_map_setup\fR(9F), \fBddi_dma_alloc_handle\fR(9F),
 135 \fBddi_dev_report_fault\fR(9F), \fBddi_get8\fR(9F), \fBddi_put8\fR(9F)