[src/trunk]: src/share/man/man9 Manual page describing interface between scsi...

To: source-changes-hg%NetBSD.org@localhost
Subject: [src/trunk]: src/share/man/man9 Manual page describing interface between scsi...
From: bouyer <bouyer%NetBSD.org@localhost>
Date: Fri, 24 Jan 2020 09:10:33 +0000
details:   https://anonhg.NetBSD.org/src/rev/7f5b90403790
branches:  trunk
changeset: 509739:7f5b90403790
user:      bouyer <bouyer%NetBSD.org@localhost>
date:      Fri May 11 08:51:15 2001 +0000

description:
Manual page describing interface between scsipi middle-layer and host bus
adapters.

diffstat:

 share/man/man9/Makefile |    4 +-
 share/man/man9/scsipi.9 |  550 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 552 insertions(+), 2 deletions(-)

diffs (truncated from 572 to 300 lines):

diff -r f26a3ab15e1b -r 7f5b90403790 share/man/man9/Makefile
--- a/share/man/man9/Makefile   Fri May 11 06:10:44 2001 +0000
+++ b/share/man/man9/Makefile   Fri May 11 08:51:15 2001 +0000
@@ -1,4 +1,4 @@
-#       $NetBSD: Makefile,v 1.76 2001/05/11 02:35:06 eeh Exp $
+#       $NetBSD: Makefile,v 1.77 2001/05/11 08:51:15 bouyer Exp $
 
 #      Makefile for section 9 (kernel function and variable) manual pages.
 
@@ -10,7 +10,7 @@
        microtime.9 panic.9 pci_configure_bus.9 pci_intr.9 pfil.9 physio.9 \
        pmap.9 pool.9 powerhook_establish.9 ppsratecheck.9 psignal.9 \
        ratecheck.9 resettodr.9 rnd.9 rt_timer.9 \
-       shutdownhook_establish.9 sleep.9 softintr.9 \
+       scsipi.9 shutdownhook_establish.9 sleep.9 softintr.9 \
        spl.9 store.9 time.9 todr.9 uiomove.9 ucom.9 \
        usbdi.9 uvm.9 wdc.9
 MLINKS+=arp.9 arp_ifinit.9 arp.9 arpresolve.9 arp.9 arpintr.9
diff -r f26a3ab15e1b -r 7f5b90403790 share/man/man9/scsipi.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/scsipi.9   Fri May 11 08:51:15 2001 +0000
@@ -0,0 +1,550 @@
+.\"    $NetBSD: scsipi.9,v 1.1 2001/05/11 08:51:15 bouyer Exp $
+.\"
+.\"
+.\" Copyright (c) 2001 Manuel Bouyer.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"    This product includes software developed by the University of
+.\"    California, Berkeley and its contributors.
+.\" 4. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,     
+.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.\"
+.Dd April 22, 2001
+.Dt SCSIPI 9
+.Os
+.Sh NAME
+.Nm scsipi
+.Nd SCSI/ATAPI middle-layer interface
+.Sh SYNOPSIS
+.Fd #include <dev/scsipi/atapiconf.h>
+.Fd #include <dev/scsipi/scsiconf.h>
+.Ft void
+.Fn scsipi_async_event "struct scsipi_channel *chan" "scsipi_async_event_t event" "void *arg"
+.Ft void
+.Fn scsipi_channel_freeze "struct scsipi_channel *chan" "int count"
+.Ft void
+.Fn scsipi_channel_thaw "struct scsipi_channel *chan" "int count"
+.Ft void
+.Fn scsipi_channel_timed_thaw "void *arg"
+.Ft void
+.Fn scsipi_periph_freeze "struct scsipi_periph *periph" "int count"
+.Ft void
+.Fn scsipi_periph_thaw "struct scsipi_periph *periph" "int count"
+.Ft void
+.Fn scsipi_periph_timed_thaw "void *arg"
+.Ft void
+.Fn scsipi_done "struct scsipi_xfer *xs"
+.Ft void
+.Fn scsipi_printaddr "struct scsipi_periph *periph"
+.Sh DESCRIPTION
+The
+.Nm
+system is the middle layer interface between SCSI/ATAPI host bus
+adapters (HBA) and high-level SCSI/ATAPI drivers.  This document
+describes the interfaces provided by the
+.Nm
+layer towards the HBA layer.  An HBA has to provide a pointer to a
+.Va struct scsipi_adapter
+and one pointer per channel to a
+.Va struct scsipi_channel .
+Once the SCSI or ATAPI bus is attached, the
+.Nm
+system will scan the bus and allocate a
+.Va struct scsipi_periph
+for each device found on the bus.  A high-level command (command sent from
+the high-level SCSI/ATAPI layer to the low-level HBA layer) is described by a
+.Va struct scsipi_xfer .
+.Pp
+A request is sent to the HBA driver though the
+.Fn adapt_request
+callback.  The HBA driver signals completion (with or without errors) of the
+request though
+.Fn scsipi_done .
+.Nm
+knows the resources limits of the HBA (max number of concurrent requests per
+adapter of channel, and per periph), and will make sure the HBA won't receive
+more requests than it can handle.
+.Pp
+The mid-layer can also handle
+.Dv QUEUE FULL
+and
+.Dv CHECK CONDITION
+events.
+.Ss INITIALISATION
+An HBA driver has to allocate and initialize to 0 a
+.Va struct scsipi_adapter
+and fill in the following members:
+.Bl -tag -width "struct_device *adapt_dev" -compact -offset indent
+.It Va struct device *adapt_dev
+pointer to the HBA's
+.Va struct device
+.It Va int adapt_nchannels
+number of channels (or busses) of the adapter
+.It Va int adapt_openings
+total number of commands the adapter can handle (may be replaced by
+.Va chan_openings ,
+see below)
+.It Va int adapt_max_periph
+number of commands the adapter can handle per device
+.El
+.Pp
+The following callbacks should be provided through the
+.Va struct scsipi_adapter :
+.Bl -tag -width someverylongword -compact -offset indent
+.It void Fn (*adapt_request) "struct scsipi_channel *" "scsipi_adapter_req_t" "void *"
+mandatory
+.It void Fn (*adapt_minphys) "struct buf *"
+mandatory
+.It int Fn (*adapt_ioctl) "struct scsipi_channel *" "u_long" "caddr_t" "int" "struct proc *"
+optional
+.It int Fn (*adapt_enable) "struct device *" "int"
+optional, set to
+.Dv NULL
+if not used
+.It int Fn (*adapt_getgeom) "struct scsipi_periph *" "struct disk_parms *" "u_long"
+optional, set to
+.Dv NULL
+if not used
+.It int Fn (*adapt_accesschk) "struct scsipi_periph *" "struct scsipi_inquiry_pattern *"
+optional, set to
+.Dv NULL
+if not used
+.El
+.Pp
+The HBA driver has to allocate and initialize to 0 one
+.Va struct scsipi_channel
+per channel and fill in the following members:
+.Bl -tag -width struct_scsipi_adapter -compact -offset indent
+.It Va struct scsipi_adapter *chan_adapter
+Pointer to the HBA's
+.Fa struct scsipi_adapter
+.It Va struct scsipi_bustype *chan_bustype
+should be initialized to either
+.Va bus_atapi
+or
+.Va bus_scsi ,
+both defined in the
+.Nm
+code.
+.It Va int chan_channel
+channel number (starting at 0)
+.It Va int chan_flags
+channel flags:
+.Bl -tag -width SCSIPI_CHAN_OPENINGS -compact
+.It Dv SCSIPI_CHAN_OPENINGS
+Use per-channel max number of commands
+.Va chan_openings
+instead of per-adapter
+.Va adapt_openings
+.It Dv SCSIPI_CHAN_CANGROW
+This channel can grow its
+.Va chan_openings
+or
+.Va adapt_openings
+on request (via the
+.Fn adapt_request
+callback)
+.It Dv SCSIPI_CHAN_NOSETTLE
+Do not wait SCSI_DELAY seconds for devices to settle before probing (usually
+used by adapters that provide an \*qabstracted\*q view of the bus).
+.El
+.It Va int chan_openings
+total number of commands the adapter can handle for this channel (used only
+if the
+.Dv SCSIPI_CHAN_OPENINGS
+flag is set)
+.It Va chan_max_periph
+number of commands per device the adapter can handle on this
+channel (used only if the
+.Va SCSIPI_CHAN_OPENINGS
+flag is set)
+.It Va int chan_ntargets
+number of targets
+.It Va int chan_nluns
+number of LUNs per target
+.It Va int chan_id
+adapter's ID on this channel
+.It Va int chan_defquirks
+default device quirks.  Quirks are defined in
+.Pa <dev/scsipi/scsipiconf.h>
+and are usually set in the middle layer based on the device's inquiry
+data.  For some kinds of adapters it may be convenient to have a set of
+quirks applied to all devices, regardless of the inquiry data.
+.El
+.Pp
+The HBA driver attaches the SCSI or ATAPI bus (depending on the setting of
+.Va chan_bustype )
+by passing a pointer to the
+.Va struct scsipi_channel
+to the 
+.Xr autoconf 4
+machinery.  The print function shall be either
+.Fn scsiprint
+or
+.Fn atapiprint .
+.Ss OTHER DATA STRUCTURES
+When scanning the bus, the
+.Nm
+system allocates a
+.Va struct scsipi_periph
+for each device probed.  The interesting fields are:
+.Bl -tag -width int_periph_openings -compact -offset indent
+.It Va struct device *periph_dev
+pointer to the device's
+.Va struct device
+.It Va struct scsipi_channel *periph_channel
+pointer to the channel the device is connected to
+.It Va int periph_quirks
+device quirks, defined in
+.Aq Pa dev/scsipi/scsipiconf.h 
+.It Va int periph_target
+target ID, or drive number on ATAPI
+.It Va int periph_lun
+LUN (currently not used on ATAPI)
+.El
+.Pp
+A SCSI or ATAPI request is passed to the HBA through a
+.Va struct scsipi_xfer .
+The HBA driver has access to the following data:
+.Bl -tag -width "int xs_callout" -compact -offset indent
+.It Va struct callout xs_callout
+callout for adapter use, usually for command timeout
+.It Va int xs_control
+control flags (only flags of interest for HBA drivers are described):
+.Bl -tag -width XS_CTL_DISCOVERY -compact
+.It Dv XS_CTL_POLL
+poll in the HBA driver for request completion (most likely because interrupts
+are disabled)
+.It Dv XS_CTL_RESET
+reset the device
+.It Dv XS_CTL_DATA_UIO
+xs_data points to a
+.Fa struct uio
+buffer
+.It Dv XS_CTL_DATA_IN
+data is transferred from HBA to memory
+.It Dv XS_CTL_DATA_OUT
+data is transferred from memory to HBA
+.It Dv XS_CTL_DISCOVERY
+this xfer is part of a device discovery done by the middle layer
+.It Dv XS_CTL_REQSENSE
+xfer is a request sense
+.El
+.Pp
+.It Va int xs_status
+status flags:
+.Bl -tag -width XS_STS_PRIVATE -compact
+.It Va XS_STS_DONE
+xfer is done (set by
+.Fn scsipi_done )
+.It Va XS_STS_PRIVATE
+mask of flags reserved for HBA's use (0xf0000000)
+.El
+.Pp
+.It Va struct scsipi_periph *xs_periph
+periph doing the xfer
+.It Va int timeout
+command timeout, in milliseconds.  The HBA should start the timeout at the time
+the command is accepted by the device.  If the timeout happens, the HBA shall
+terminate the command through
+.Fn scsipi_done
+with a XS_TIMEOUT error
+.It Va struct scsipi_generic *cmd
+scsipi command to execute
+.It Va int cmdlen
+len (in bytes) of the cmd buffer
+.It Va u_char *data
Prev by Date: [src/trunk]: src/share/wscons/keymaps Add keymap file for "swedish keyboard w...
Next by Date: [src/trunk]: src/sys/arch/sgimips/dev Support for the SCC serial ports on Ind...
Previous by Thread: [src/trunk]: src/share/wscons/keymaps Add keymap file for "swedish keyboard w...
Next by Thread: [src/trunk]: src/sys/arch/sgimips/dev Support for the SCC serial ports on Ind...
Indexes:
Home | Main Index | Thread Index | Old Index