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 ALSOddi_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)