share/man/man9f/ddi_fm_acc_err_get.9f

   1 '\" te
   2 .\" Copyright (c) 2007, 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_FM_ACC_ERR_GET 9F "Mar 27, 2016"
   7 .SH NAME
   8 ddi_fm_acc_err_get, ddi_fm_dma_err_get \- get the error status for an access or
   9 DMA handle
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/ddifm.h>
  14
  15 \fBvoid\fR \fBddi_fm_acc_err_get\fR(\fBddi_acc_handle_t\fR \fIacc_handle\fR,
  16      \fBddi_fm_error_t\fR *\fIerror_status\fR, \fBint\fR \fIversion\fR);
  17 .fi
  18
  19 .LP
  20 .nf
  21 \fBvoid\fR \fBddi_fm_dma_err_get\fR(\fBddi_dma_handle_t\fR \fIdma_handle\fR,
  22      \fBddi_fm_error_t\fR *\fIerror_status\fR, \fBint\fR \fIversion\fR);
  23 .fi
  24
  25 .SH INTERFACE LEVEL
  26 .LP
  27 Solaris DDI specific (Solaris DDI)
  28 .SH PARAMETERS
  29 .ne 2
  30 .na
  31 \fB\fIacc_handle\fR\fR
  32 .ad
  33 .RS 16n
  34 Data access handle obtained from a previous call to
  35 \fBddi_regs_map_setup\fR(9F), \fBddi_dma_mem_alloc\fR(9F), or to a similar
  36 function.
  37 .RE
  38
  39 .sp
  40 .ne 2
  41 .na
  42 \fB\fIdma_handle\fR\fR
  43 .ad
  44 .RS 16n
  45 \fBDMA\fR handle obtained from a previous call to \fBddi_dma_mem_alloc\fR(9F)
  46 or one of its derivatives.
  47 .RE
  48
  49 .sp
  50 .ne 2
  51 .na
  52 \fB\fIerror_status\fR\fR
  53 .ad
  54 .RS 16n
  55 Pointer to where the error status for the access or \fBDMA\fR handle should be
  56 returned.
  57 .RE
  58
  59 .sp
  60 .ne 2
  61 .na
  62 \fB\fIversion\fR\fR
  63 .ad
  64 .RS 16n
  65 Version number of \fBddi_fm_error_t\fR. The driver should always set this to
  66 \fBDDI_FME_VERSION\fR.
  67 .RE
  68
  69 .SH DESCRIPTION
  70 .LP
  71 The \fBddi_fm_dma_err_get()\fR and \fBddi_fm_acc_err_get()\fR functions return
  72 the error status for a \fBDMA\fR or access handle respectively. If a fault has
  73 occurred that affects the resource mapped by the supplied handle, the supplied
  74 \fIerror_status\fR structure is updated to reflect error information captured
  75 during error handling by a bus or other device driver in the \fBI/O\fR data
  76 path.
  77 .sp
  78 .LP
  79 If an error is indicated for an access handle, the driver might no longer be
  80 able to access the mapped registers or memory using programmed \fBI/O\fR
  81 through the handle. Typically, this might occur after the device has failed to
  82 respond to an \fBI/O\fR access - in the case of a bus error, for instance, or a
  83 timeout. The effect of programmed \fBI/O\fR access made at the time of a fault
  84 is undefined. Read access via \fBddi_get8\fR(9F), for example, can return
  85 random values, while write access via \fBddi_put8\fR(9F) might or might not
  86 have an effect. It is possible, however, that the error might be transient. In
  87 that case, the driver can attempt to recover by calling
  88 \fBddi_fm_acc_err_clear()\fR, resetting the device to return it to a known
  89 state, then retrying any potentially failed transactions.
  90 .sp
  91 .LP
  92 If an error is indicated for a \fBDMA\fR handle, it implies that an error has
  93 been detected that has or will affect \fBDMA\fR transactions between the device
  94 and the memory currently bound to the handle - or the memory most recently
  95 bound, if the handle is currently unbound. Possible causes include the failure
  96 of a component in the \fBDMA\fR data path or an attempt by the device to make
  97 an invalid \fBDMA\fR access. The contents of any memory currently or previously
  98 bound to the handle should be considered indeterminate. The driver might be
  99 able to continue by freeing memory that is bound to the handle back to the
 100 system, resetting the device to return it to a known state, then retrying any
 101 potentially failed transactions.
 102 .sp
 103 .LP
 104 If the driver is unable to recover, the operating state should be changed by a
 105 call to \fBddi_fm_service_impact()\fR that specifies \fBDDI_SERVICE_LOST\fR for
 106 the impacted device instance. If the recovery and retry succeed, a call should
 107 still be made to \fBddi_fm_service_impact()\fR but \fBDDI_SERVICE_UNAFFECTED\fR
 108 should be specified.
 109 .SH CONTEXT
 110 .LP
 111 The \fBddi_fm_acc_err_get()\fR and \fBddi_fm_dma_err_get()\fR functions can be
 112 called from user, kernel, or high-level interrupt context.
 113 .SH ATTRIBUTES
 114 .LP
 115 See \fBattributes\fR(5) for descriptions of the following attributes:
 116 .sp
 117
 118 .sp
 119 .TS
 120 box;
 121 c | c
 122 l | l .
 123 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 124 _
 125 Interface Stability     Committed
 126 .TE
 127
 128 .SH SEE ALSO
 129 .LP
 130 \fBattributes\fR(5), \fBddi_dma_mem_alloc\fR(9F),
 131 \fBddi_fm_acc_err_clear\fR(9F), \fBddi_fm_service_impact\fR(9F),
 132 \fBddi_get8\fR(9F), \fBddi_put8\fR(9F), \fBddi_regs_map_setup\fR(9F),
 133 \fBddi_fm_error\fR(9S),
 134 .sp
 135 .LP
 136 \fIWriting Device Drivers\fR