'\" te
.\"  Copyright (c) 1999, Sun Microsystems, Inc.  All Rights Reserved
.\" 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.
.\" 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.
.\" 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]
.TH DDI_CHECK_ACC_HANDLE 9F "Aug 13, 1999"
.SH NAME
ddi_check_acc_handle, ddi_check_dma_handle \- Check data access and DMA handles
.SH SYNOPSIS
.LP
.nf
#include <sys/ddi.h>
#include <sys/sunddi.h>



\fBint\fR \fBddi_check_acc_handle\fR(\fBddi_acc_handle_t\fR \fI acc_handle\fR );
.fi

.LP
.nf
\fBint\fR \fBddi_check_dma_handle\fR(\fBddi_dma_handle_t\fR  \fIdma_handle\fR );
.fi

.SH INTERFACE LEVEL
.sp
.LP
Solaris DDI specific (Solaris DDI)
.SH PARAMETERS
.sp
.ne 2
.na
\fB\fIacc_handle\fR \fR
.ad
.RS 15n
Data access handle obtained from a previous call to
\fBddi_regs_map_setup\fR(9F), \fBddi_dma_mem_alloc\fR(9F), or similar function.
.RE

.sp
.ne 2
.na
\fB\fIdma_handle\fR \fR
.ad
.RS 15n
DMA handle obtained from a previous call to \fBddi_dma_setup\fR(9F) or one of
its derivatives.
.RE

.SH DESCRIPTION
.sp
.LP
The \fBddi_check_acc_handle()\fR\fB and ddi_check_dma_handle()\fR 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.
.sp
.LP
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,
\fBddi_get8\fR(9F)) may return random values, and write accesses (for example,
\fBddi_put8\fR(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 \fBddi_dev_report_fault\fR(9F) specifying \fBDDI_SERVICE_LOST\fR for the
impact, and \fBDDI_DATAPATH_FAULT\fR for the location.
.sp
.LP
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.
.sp
.LP
Note that 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 \fBdoes\fR exist with respect to communication using that handle.
.SH RETURN VALUES
.sp
.LP
The \fBddi_check_acc_handle()\fR and \fBddi_check_dma_handle()\fR functions
return \fBDDI_SUCCESS\fR if no faults affecting the supplied handle are
detected and \fBDDI_FAILURE\fR if any fault affecting the supplied handle is
detected.
.SH EXAMPLES
.sp
.in +2
.nf
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);
    }
    \&...
.fi
.in -2

.SH CONTEXT
.sp
.LP
The \fBddi_check_acc_handle()\fR and \fBddi_check_dma_handle()\fR functions may
be called from user, kernel, or interrupt context.
.SH SEE ALSO
.sp
.LP
\fBddi_regs_map_setup\fR(9F), \fBddi_dma_setup\fR(9F),
\fBddi_dev_report_fault\fR(9F), \fBddi_get8\fR(9F), \fBddi_put8\fR(9F)