'\" 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 "26 Feb 2002" "SunOS 5.11" "Kernel Functions for Drivers"
.SH NAME
scsi_probe \- utility for probing a scsi device
.SH SYNOPSIS
.LP
.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
.sp
.LP
Solaris DDI specific (Solaris DDI).
.SH PARAMETERS
.sp
.ne 2
.mk
.na
\fB\fIdevp\fR \fR
.ad
.RS 13n
.rt  
Pointer to a \fBscsi_device\fR(9S) structure
.RE

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

.SH DESCRIPTION
.sp
.LP
\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
.mk
.na
\fB\fBNULL_FUNC\fR \fR
.ad
.RS 15n
.rt  
Do not wait for resources. Return \fBSCSIPROBE_NOMEM\fR or
\fBSCSIPROBE_FAILURE\fR
.RE

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

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

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

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

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

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

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

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

.SH CONTEXT
.sp
.LP
\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
.LP
\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
.sp
.LP
\fBattach\fR(9E), \fBprobe\fR(9E), \fBscsi_slave\fR(9F),
\fBscsi_unprobe\fR(9F), \fBscsi_unslave\fR(9F), \fBscsi_device\fR(9S),
\fBscsi_inquiry\fR(9S)
.sp
.LP
\fIANSI Small Computer System Interface-2 (SCSI-2)\fR
.sp
.LP
\fIWriting Device Drivers\fR
.SH NOTES
.sp
.LP
A \fIwaitfunc\fR function other than \fBNULL_FUNC\fR or \fBSLEEP_FUNC\fR is not
supported and may have unexpected results.