'\" te
.\" Copyright (c) 2002, Sun Microsystems, Inc.
.\" 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 SCSI_PROBE 9F "Feb 26, 2002"
.SH NAME
scsi_probe \- utility for probing a scsi device
.SH SYNOPSIS
.nf
#include <sys/scsi/scsi.h>



\fBint\fR \fBscsi_probe\fR(\fBstruct scsi_device *\fR\fIdevp\fR, \fBint (*\fR\fIwaitfunc\fR);
.fi

.SH INTERFACE LEVEL
illumos DDI specific (illumos DDI).
.SH PARAMETERS
.ne 2
.na
\fB\fIdevp\fR \fR
.ad
.RS 13n
Pointer to a \fBscsi_device\fR(9S) structure
.RE

.sp
.ne 2
.na
\fB\fIwaitfunc\fR \fR
.ad
.RS 13n
\fBNULL_FUNC\fR or \fBSLEEP_FUNC\fR
.RE

.SH DESCRIPTION
\fBscsi_probe()\fR determines whether a \fBtarget/lun\fR is present and sets up
the \fBscsi_device\fR structure with inquiry data.
.sp
.LP
\fBscsi_probe()\fR uses the SCSI Inquiry command to test if the device exists.
It can retry the Inquiry command as appropriate. If \fBscsi_probe()\fR is
successful, it will allocate space for the \fBscsi_inquiry\fR structure and
assign the address to the \fBsd_inq\fR member of the \fBscsi_device\fR(9S)
structure. \fBscsi_probe()\fR will then fill in this \fBscsi_inquiry\fR(9S)
structure and return \fBSCSIPROBE_EXISTS\fR. If \fBscsi_probe()\fR is
unsuccessful, it returns \fBSCSIPROBE_NOMEM\fR in spite of callback set to
\fBSLEEP_FUNC\fR.
.sp
.LP
\fBscsi_unprobe\fR(9F) is used to undo the effect of \fBscsi_probe()\fR.
.sp
.LP
If the target is a non-CCS device, \fBSCSIPROBE_NONCCS\fR will be returned.
.sp
.LP
\fIwaitfunc\fR indicates what the allocator routines should do when resources
are not available; the valid values are:
.sp
.ne 2
.na
\fB\fBNULL_FUNC\fR \fR
.ad
.RS 15n
Do not wait for resources. Return \fBSCSIPROBE_NOMEM\fR or
\fBSCSIPROBE_FAILURE\fR
.RE

.sp
.ne 2
.na
\fB\fBSLEEP_FUNC\fR \fR
.ad
.RS 15n
Wait indefinitely for resources.
.RE

.SH RETURN VALUES
\fBscsi_probe()\fR returns:
.sp
.ne 2
.na
\fB\fBSCSIPROBE_BUSY\fR \fR
.ad
.RS 23n
Device exists but is currently busy.
.RE

.sp
.ne 2
.na
\fB\fBSCSIPROBE_EXISTS\fR \fR
.ad
.RS 23n
Device exists and inquiry data is valid.
.RE

.sp
.ne 2
.na
\fB\fBSCSIPROBE_FAILURE\fR \fR
.ad
.RS 23n
Polled command failure.
.RE

.sp
.ne 2
.na
\fB\fBSCSIPROBE_NOMEM\fR \fR
.ad
.RS 23n
No space available for structures.
.RE

.sp
.ne 2
.na
\fB\fBSCSIPROBE_NOMEM_CB\fR \fR
.ad
.RS 23n
No space available for structures but callback request has been queued.
.RE

.sp
.ne 2
.na
\fB\fBSCSIPROBE_NONCCS\fR \fR
.ad
.RS 23n
Device exists but inquiry data is not valid.
.RE

.sp
.ne 2
.na
\fB\fBSCSIPROBE_NORESP\fR \fR
.ad
.RS 23n
Device does not respond to an INQUIRY.
.RE

.SH CONTEXT
\fBscsi_probe()\fR is normally called from the target driver's \fBprobe\fR(9E)
or \fBattach\fR(9E) routine. In any case, this routine should not be called
from interrupt context, because it can sleep waiting for memory to be
allocated.
.SH EXAMPLES
\fBExample 1 \fR Using \fBscsi_probe()\fR
.sp
.in +2
.nf
    switch (scsi_probe(devp, NULL_FUNC)) {
    default:
    case SCSIPROBE_NORESP:
    case SCSIPROBE_NONCCS:
    case SCSIPROBE_NOMEM:
    case SCSIPROBE_FAILURE:
    case SCSIPROBE_BUSY:
            break;
    case SCSIPROBE_EXISTS:
            switch (devp->sd_inq->inq_dtype) {
            case DTYPE_DIRECT:
                    rval = DDI_PROBE_SUCCESS;
                    break;
            case DTYPE_RODIRECT:
                    rval = DDI_PROBE_SUCCESS;
                    break;
            case DTYPE_NOTPRESENT:
            default:
                    break;
            }
    }
    scsi_unprobe(devp);
.fi
.in -2

.SH SEE ALSO
.BR attach (9E),
.BR probe (9E),
.BR scsi_slave (9F),
.BR scsi_unprobe (9F),
.BR scsi_unslave (9F),
.BR scsi_device (9S),
.BR scsi_inquiry (9S)
.sp
.LP
\fIANSI Small Computer System Interface-2 (SCSI-2)\fR
.sp
.LP
\fIWriting Device Drivers\fR
.SH NOTES
A \fIwaitfunc\fR function other than \fBNULL_FUNC\fR or \fBSLEEP_FUNC\fR is not
supported and may have unexpected results.