usr/src/man/man9f/scsi_probe.9f

   1 '\" te
   2 .\" Copyright (c) 2002, Sun Microsystems, Inc.
   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 SCSI_PROBE 9F "Feb 26, 2002"
   7 .SH NAME
   8 scsi_probe \- utility for probing a scsi device
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/scsi/scsi.h>
  13
  14
  15
  16 \fBint\fR \fBscsi_probe\fR(\fBstruct scsi_device *\fR\fIdevp\fR, \fBint (*\fR\fIwaitfunc\fR);
  17 .fi
  18
  19 .SH INTERFACE LEVEL
  20 .sp
  21 .LP
  22 Solaris DDI specific (Solaris DDI).
  23 .SH PARAMETERS
  24 .sp
  25 .ne 2
  26 .na
  27 \fB\fIdevp\fR \fR
  28 .ad
  29 .RS 13n
  30 Pointer to a \fBscsi_device\fR(9S) structure
  31 .RE
  32
  33 .sp
  34 .ne 2
  35 .na
  36 \fB\fIwaitfunc\fR \fR
  37 .ad
  38 .RS 13n
  39 \fBNULL_FUNC\fR or \fBSLEEP_FUNC\fR
  40 .RE
  41
  42 .SH DESCRIPTION
  43 .sp
  44 .LP
  45 \fBscsi_probe()\fR determines whether a \fBtarget/lun\fR is present and sets up
  46 the \fBscsi_device\fR structure with inquiry data.
  47 .sp
  48 .LP
  49 \fBscsi_probe()\fR uses the SCSI Inquiry command to test if the device exists.
  50 It can retry the Inquiry command as appropriate. If \fBscsi_probe()\fR is
  51 successful, it will allocate space for the \fBscsi_inquiry\fR structure and
  52 assign the address to the \fBsd_inq\fR member of the \fBscsi_device\fR(9S)
  53 structure. \fBscsi_probe()\fR will then fill in this \fBscsi_inquiry\fR(9S)
  54 structure and return \fBSCSIPROBE_EXISTS\fR. If \fBscsi_probe()\fR is
  55 unsuccessful, it returns \fBSCSIPROBE_NOMEM\fR in spite of callback set to
  56 \fBSLEEP_FUNC\fR.
  57 .sp
  58 .LP
  59 \fBscsi_unprobe\fR(9F) is used to undo the effect of \fBscsi_probe()\fR.
  60 .sp
  61 .LP
  62 If the target is a non-CCS device, \fBSCSIPROBE_NONCCS\fR will be returned.
  63 .sp
  64 .LP
  65 \fIwaitfunc\fR indicates what the allocator routines should do when resources
  66 are not available; the valid values are:
  67 .sp
  68 .ne 2
  69 .na
  70 \fB\fBNULL_FUNC\fR \fR
  71 .ad
  72 .RS 15n
  73 Do not wait for resources. Return \fBSCSIPROBE_NOMEM\fR or
  74 \fBSCSIPROBE_FAILURE\fR
  75 .RE
  76
  77 .sp
  78 .ne 2
  79 .na
  80 \fB\fBSLEEP_FUNC\fR \fR
  81 .ad
  82 .RS 15n
  83 Wait indefinitely for resources.
  84 .RE
  85
  86 .SH RETURN VALUES
  87 .sp
  88 .LP
  89 \fBscsi_probe()\fR returns:
  90 .sp
  91 .ne 2
  92 .na
  93 \fB\fBSCSIPROBE_BUSY\fR \fR
  94 .ad
  95 .RS 23n
  96 Device exists but is currently busy.
  97 .RE
  98
  99 .sp
 100 .ne 2
 101 .na
 102 \fB\fBSCSIPROBE_EXISTS\fR \fR
 103 .ad
 104 .RS 23n
 105 Device exists and inquiry data is valid.
 106 .RE
 107
 108 .sp
 109 .ne 2
 110 .na
 111 \fB\fBSCSIPROBE_FAILURE\fR \fR
 112 .ad
 113 .RS 23n
 114 Polled command failure.
 115 .RE
 116
 117 .sp
 118 .ne 2
 119 .na
 120 \fB\fBSCSIPROBE_NOMEM\fR \fR
 121 .ad
 122 .RS 23n
 123 No space available for structures.
 124 .RE
 125
 126 .sp
 127 .ne 2
 128 .na
 129 \fB\fBSCSIPROBE_NOMEM_CB\fR \fR
 130 .ad
 131 .RS 23n
 132 No space available for structures but callback request has been queued.
 133 .RE
 134
 135 .sp
 136 .ne 2
 137 .na
 138 \fB\fBSCSIPROBE_NONCCS\fR \fR
 139 .ad
 140 .RS 23n
 141 Device exists but inquiry data is not valid.
 142 .RE
 143
 144 .sp
 145 .ne 2
 146 .na
 147 \fB\fBSCSIPROBE_NORESP\fR \fR
 148 .ad
 149 .RS 23n
 150 Device does not respond to an INQUIRY.
 151 .RE
 152
 153 .SH CONTEXT
 154 .sp
 155 .LP
 156 \fBscsi_probe()\fR is normally called from the target driver's \fBprobe\fR(9E)
 157 or \fBattach\fR(9E) routine. In any case, this routine should not be called
 158 from interrupt context, because it can sleep waiting for memory to be
 159 allocated.
 160 .SH EXAMPLES
 161 .LP
 162 \fBExample 1 \fR Using \fBscsi_probe()\fR
 163 .sp
 164 .in +2
 165 .nf
 166     switch (scsi_probe(devp, NULL_FUNC)) {
 167     default:
 168     case SCSIPROBE_NORESP:
 169     case SCSIPROBE_NONCCS:
 170     case SCSIPROBE_NOMEM:
 171     case SCSIPROBE_FAILURE:
 172     case SCSIPROBE_BUSY:
 173             break;
 174     case SCSIPROBE_EXISTS:
 175             switch (devp->sd_inq->inq_dtype) {
 176             case DTYPE_DIRECT:
 177                     rval = DDI_PROBE_SUCCESS;
 178                     break;
 179             case DTYPE_RODIRECT:
 180                     rval = DDI_PROBE_SUCCESS;
 181                     break;
 182             case DTYPE_NOTPRESENT:
 183             default:
 184                     break;
 185             }
 186     }
 187     scsi_unprobe(devp);
 188 .fi
 189 .in -2
 190
 191 .SH SEE ALSO
 192 .sp
 193 .LP
 194 \fBattach\fR(9E), \fBprobe\fR(9E), \fBscsi_slave\fR(9F),
 195 \fBscsi_unprobe\fR(9F), \fBscsi_unslave\fR(9F), \fBscsi_device\fR(9S),
 196 \fBscsi_inquiry\fR(9S)
 197 .sp
 198 .LP
 199 \fIANSI Small Computer System Interface-2 (SCSI-2)\fR
 200 .sp
 201 .LP
 202 \fIWriting Device Drivers\fR
 203 .SH NOTES
 204 .sp
 205 .LP
 206 A \fIwaitfunc\fR function other than \fBNULL_FUNC\fR or \fBSLEEP_FUNC\fR is not
 207 supported and may have unexpected results.