1.\" $NetBSD: scsipi.9,v 1.4 2001/07/18 20:35:36 bouyer Exp $ 2.\" 3.\" 4.\" Copyright (c) 2001 Manuel Bouyer. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the University of 17.\" California, Berkeley and its contributors. 18.\" 4. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 23.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 24.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 25.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 26.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 27.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 28.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 29.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 30.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 31.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 32.\" 33.\" 34.Dd April 22, 2001 35.Dt SCSIPI 9 36.Os 37.Sh NAME 38.Nm scsipi 39.Nd SCSI/ATAPI middle-layer interface 40.Sh SYNOPSIS 41.Fd #include <dev/scsipi/atapiconf.h> 42.Fd #include <dev/scsipi/scsiconf.h> 43.Ft void 44.Fn scsipi_async_event "struct scsipi_channel *chan" "scsipi_async_event_t event" "void *arg" 45.Ft void 46.Fn scsipi_channel_freeze "struct scsipi_channel *chan" "int count" 47.Ft void 48.Fn scsipi_channel_thaw "struct scsipi_channel *chan" "int count" 49.Ft void 50.Fn scsipi_channel_timed_thaw "void *arg" 51.Ft void 52.Fn scsipi_periph_freeze "struct scsipi_periph *periph" "int count" 53.Ft void 54.Fn scsipi_periph_thaw "struct scsipi_periph *periph" "int count" 55.Ft void 56.Fn scsipi_periph_timed_thaw "void *arg" 57.Ft void 58.Fn scsipi_done "struct scsipi_xfer *xs" 59.Ft void 60.Fn scsipi_printaddr "struct scsipi_periph *periph" 61.Ft int 62.Fn scsipi_target_detach "struct scsipi_channel *chan" "int target" "int lun" "int flags" 63.Ft int 64.Fn scsipi_thread_call_callback "struct scsipi_channel *chan" "void (*callback) __P((struct scsipi_channel *, void *))" "void *arg" 65.Sh DESCRIPTION 66The 67.Nm 68system is the middle layer interface between SCSI/ATAPI host bus 69adapters (HBA) and high-level SCSI/ATAPI drivers. This document 70describes the interfaces provided by the 71.Nm 72layer towards the HBA layer. An HBA has to provide a pointer to a 73.Va struct scsipi_adapter 74and one pointer per channel to a 75.Va struct scsipi_channel . 76Once the SCSI or ATAPI bus is attached, the 77.Nm 78system will scan the bus and allocate a 79.Va struct scsipi_periph 80for each device found on the bus. A high-level command (command sent from 81the high-level SCSI/ATAPI layer to the low-level HBA layer) is described by a 82.Va struct scsipi_xfer . 83.Pp 84A request is sent to the HBA driver though the 85.Fn adapt_request 86callback. The HBA driver signals completion (with or without errors) of the 87request though 88.Fn scsipi_done . 89.Nm 90knows the resources limits of the HBA (max number of concurrent requests per 91adapter of channel, and per periph), and will make sure the HBA won't receive 92more requests than it can handle. 93.Pp 94The mid-layer can also handle 95.Dv QUEUE FULL 96and 97.Dv CHECK CONDITION 98events. 99.Ss INITIALISATION 100An HBA driver has to allocate and initialize to 0 a 101.Va struct scsipi_adapter 102and fill in the following members: 103.Bl -tag -width "struct_device *adapt_dev" -compact -offset indent 104.It Va struct device *adapt_dev 105pointer to the HBA's 106.Va struct device 107.It Va int adapt_nchannels 108number of channels (or busses) of the adapter 109.It Va int adapt_openings 110total number of commands the adapter can handle (may be replaced by 111.Va chan_openings , 112see below) 113.It Va int adapt_max_periph 114number of commands the adapter can handle per device 115.El 116.Pp 117The following callbacks should be provided through the 118.Va struct scsipi_adapter : 119.Bl -tag -width someverylongword -compact -offset indent 120.It void Fn (*adapt_request) "struct scsipi_channel *" "scsipi_adapter_req_t" "void *" 121mandatory 122.It void Fn (*adapt_minphys) "struct buf *" 123mandatory 124.It int Fn (*adapt_ioctl) "struct scsipi_channel *" "u_long" "caddr_t" "int" "struct proc *" 125optional 126.It int Fn (*adapt_enable) "struct device *" "int" 127optional, set to 128.Dv NULL 129if not used 130.It int Fn (*adapt_getgeom) "struct scsipi_periph *" "struct disk_parms *" "u_long" 131optional, set to 132.Dv NULL 133if not used 134.It int Fn (*adapt_accesschk) "struct scsipi_periph *" "struct scsipi_inquiry_pattern *" 135optional, set to 136.Dv NULL 137if not used 138.El 139.Pp 140The HBA driver has to allocate and initialize to 0 one 141.Va struct scsipi_channel 142per channel and fill in the following members: 143.Bl -tag -width struct_scsipi_adapter -compact -offset indent 144.It Va struct scsipi_adapter *chan_adapter 145Pointer to the HBA's 146.Fa struct scsipi_adapter 147.It Va struct scsipi_bustype *chan_bustype 148should be initialized to either 149.Va bus_atapi 150or 151.Va bus_scsi , 152both defined in the 153.Nm 154code. 155.It Va int chan_channel 156channel number (starting at 0) 157.It Va int chan_flags 158channel flags: 159.Bl -tag -width SCSIPI_CHAN_OPENINGS -compact 160.It Dv SCSIPI_CHAN_OPENINGS 161Use per-channel max number of commands 162.Va chan_openings 163instead of per-adapter 164.Va adapt_openings 165.It Dv SCSIPI_CHAN_CANGROW 166This channel can grow its 167.Va chan_openings 168or 169.Va adapt_openings 170on request (via the 171.Fn adapt_request 172callback) 173.It Dv SCSIPI_CHAN_NOSETTLE 174Do not wait SCSI_DELAY seconds for devices to settle before probing (usually 175used by adapters that provide an \*qabstracted\*q view of the bus). 176.El 177.It Va int chan_openings 178total number of commands the adapter can handle for this channel (used only 179if the 180.Dv SCSIPI_CHAN_OPENINGS 181flag is set) 182.It Va chan_max_periph 183number of commands per device the adapter can handle on this 184channel (used only if the 185.Va SCSIPI_CHAN_OPENINGS 186flag is set) 187.It Va int chan_ntargets 188number of targets 189.It Va int chan_nluns 190number of LUNs per target 191.It Va int chan_id 192adapter's ID on this channel 193.It Va int chan_defquirks 194default device quirks. Quirks are defined in 195.Pa <dev/scsipi/scsipiconf.h> 196and are usually set in the middle layer based on the device's inquiry 197data. For some kinds of adapters it may be convenient to have a set of 198quirks applied to all devices, regardless of the inquiry data. 199.El 200.Pp 201The HBA driver attaches the SCSI or ATAPI bus (depending on the setting of 202.Va chan_bustype ) 203by passing a pointer to the 204.Va struct scsipi_channel 205to the 206.Xr autoconf 4 207machinery. The print function shall be either 208.Fn scsiprint 209or 210.Fn atapiprint . 211.Ss OTHER DATA STRUCTURES 212When scanning the bus, the 213.Nm 214system allocates a 215.Va struct scsipi_periph 216for each device probed. The interesting fields are: 217.Bl -tag -width int_periph_openings -compact -offset indent 218.It Va struct device *periph_dev 219pointer to the device's 220.Va struct device 221.It Va struct scsipi_channel *periph_channel 222pointer to the channel the device is connected to 223.It Va int periph_quirks 224device quirks, defined in 225.Aq Pa dev/scsipi/scsipiconf.h 226.It Va int periph_target 227target ID, or drive number on ATAPI 228.It Va int periph_lun 229LUN (currently not used on ATAPI) 230.El 231.Pp 232A SCSI or ATAPI request is passed to the HBA through a 233.Va struct scsipi_xfer . 234The HBA driver has access to the following data: 235.Bl -tag -width "int xs_callout" -compact -offset indent 236.It Va struct callout xs_callout 237callout for adapter use, usually for command timeout 238.It Va int xs_control 239control flags (only flags of interest for HBA drivers are described): 240.Bl -tag -width XS_CTL_DISCOVERY -compact 241.It Dv XS_CTL_POLL 242poll in the HBA driver for request completion (most likely because interrupts 243are disabled) 244.It Dv XS_CTL_RESET 245reset the device 246.It Dv XS_CTL_DATA_UIO 247xs_data points to a 248.Fa struct uio 249buffer 250.It Dv XS_CTL_DATA_IN 251data is transferred from HBA to memory 252.It Dv XS_CTL_DATA_OUT 253data is transferred from memory to HBA 254.It Dv XS_CTL_DISCOVERY 255this xfer is part of a device discovery done by the middle layer 256.It Dv XS_CTL_REQSENSE 257xfer is a request sense 258.El 259.Pp 260.It Va int xs_status 261status flags: 262.Bl -tag -width XS_STS_PRIVATE -compact 263.It Va XS_STS_DONE 264xfer is done (set by 265.Fn scsipi_done ) 266.It Va XS_STS_PRIVATE 267mask of flags reserved for HBA's use (0xf0000000) 268.El 269.Pp 270.It Va struct scsipi_periph *xs_periph 271periph doing the xfer 272.It Va int timeout 273command timeout, in milliseconds. The HBA should start the timeout at the time 274the command is accepted by the device. If the timeout happens, the HBA shall 275terminate the command through 276.Fn scsipi_done 277with a XS_TIMEOUT error 278.It Va struct scsipi_generic *cmd 279scsipi command to execute 280.It Va int cmdlen 281len (in bytes) of the cmd buffer 282.It Va u_char *data 283data buffer (this is either a dma or uio address) 284.It Va int datalen 285data length (in bytes, zero if uio) 286.It Va int resid 287difference between 288.Fa datalen 289and how much data was really transferred 290.It Va scsipi_xfer_result_t error 291error value returned by the HBA driver to mid-layer. See description of 292.Fn scsipi_done 293for valid values 294.It Va union {struct scsipi_sense_data scsi_sense; u_int32_t atapi_sense;} sense 295where to store sense info if 296.Fa error 297is 298.Dv XS_SENSE 299or 300.Dv XS_SHORTSENSE 301.It Va u_int8_t status 302SCSI status; checked by middle layer when 303.Fa error is 304.Dv XS_BUSY 305(the middle layer handles 306.Dv SCSI_CHECK 307and 308.Dv SCSI_QUEUE_FULL ) 309.It Va u_int8_t xs_tag_type 310SCSI tag type, set to 0 if untagged command 311.It Va u_int8_t xs_tag_id 312tag ID, used for tagged commands 313.El 314.Ss FUNCTIONS AND CALLBACKS 315.Bl -tag -width xxxxxxxx -compact 316.It Fn (*adapt_request) "struct scsipi_channel *chan" "scsipi_adapter_req_t req" "void *arg" 317Used by the mid-layer to transmit a request to the adapter. 318.Va req 319can be one of: 320.Bl -tag -width xxxxxxxx -compact 321.It Dv ADAPTER_REQ_RUN_XFER 322request the adapter to send a command to the device. 323.Fa arg 324is a pointer to the 325.Va struct scsipi_xfer . 326Once the xfer is complete the HBA driver shall call 327.Fn scsipi_done 328with updated status and error information. 329.It Dv ADAPTER_REQ_GROW_RESOURCES 330ask the adapter to increase resources of the channel (grow 331.Va adapt_openings 332or 333.Va chan_openings ) 334if possible. Support of this feature is optional. 335.Fa arg 336must be ignored. 337.It Dv ADAPTER_REQ_SET_XFER_MODE 338set the xfer mode for a for I_T Nexus. This will be called once all 339LUNs of a target have been probed. 340.Fa arg 341points to a 342.Va struct scsipi_xfer_mode 343defined as follows: 344.Bl -tag -width int_xm_target -compact 345.It Va int xm_target 346target for I_T Nexus 347.It Va int xm_mode 348bitmask of device capabilities 349.It Va int xm_period 350sync period 351.It Va int xm_offset 352sync offset 353.El 354.Pp 355.Va xm_period 356and 357.Va xm_offset 358shall be ignored for 359.Dv ADAPTER_REQ_SET_XFER_MODE . 360.Va xm_mode 361holds the following bits: 362.Bl -tag -width xxxxxxxx -compact 363.It Dv PERIPH_CAP_SYNC 364synchronous transfers 365.It Dv PERIPH_CAP_WIDE16 36616 bit wide transfers 367.It Dv PERIPH_CAP_WIDE32 36832 bit wide transfers 369.It Dv PERIPH_CAP_TQING 370tagged queueing 371.El 372Whenever the xfer mode changes, the driver should call 373.Fn scsipi_async_event 374to notify the mid-layer. 375.El 376.Pp 377.Fn adapt_request 378may be called from interrupt context. 379.It Fn adapt_minphys 380pointer to the driver's minphys function. If the driver can handle 381transfers of size 382.Dv MAXPHYS , 383this can point to 384.Fn minphys . 385.It Fn adapt_ioctl 386ioctl function for the channel. The only ioctl supported at this level is 387.Dv SCBUSIORESET 388for which the HBA driver shall issue a SCSI reset on the channel. 389.It int Fn adapt_enable "struct device *dev" "int enable" 390Disable the adapter if 391.Va enable 392is zero, or enable it if non-zero. Returns 0 if operation is successful, 393or error from 394.Pa <sys/errno.h> . 395This callback is optional, and is useful mostly for hot-plug devices. 396For example, this callback would power on or off 397the relevant PCMCIA socket for a PCMCIA controller. 398.It int Fn adapt_getgeom "struct scsipi_periph *periph" "struct disk_parms *params" "u_long sectors" 399Optional callback, used by high-level drivers to get the fictitious geometry 400used by the controller's firmware for the specified periph. Returns 0 if 401successful. See adaptec drivers for details. 402.It int Fn adapt_accesschk "struct scsipi_periph *periph" "struct scsipi_inquiry_pattern *inqbuf" 403Optional callback; if present the mid-layer uses it to check if it can 404attach a driver to the specified periph. If the callback returns a non-zero 405value, the periph is ignored by the 406.Nm 407code. This callback is used by adapters which want to drive some devices 408themselves, for example hardware RAID controllers. 409.It Fn scsipi_async_event "struct scsipi_channel *chan" "scsipi_async_event_t event" "void *arg" 410Asynchronous event notification for the mid-layer. 411.Fa event 412can be one of: 413.Bl -tag -width xxxxxxxx -compact 414.It Dv ASYNC_EVENT_MAX_OPENINGS 415set max openings for a periph. Argument is a 416.Va struct scsipi_max_openings 417with at least the following members: 418.Bl -tag -width xxxxxxxx -compact 419.It Va int mo_target 420.It Va int mo_lun 421.It Va int mo_openings 422.El 423.Pp 424Not all periphs may allow openings to increase; if not allowed the request is 425silently ignored. 426.It Dv ASYNC_EVENT_XFER_MODE 427update the xfer mode for an I_T nexus. Argument is a 428.Va struct scsipi_xfer_mode 429properly filled in. An 430.Fa Dv ASYNC_EVENT_XFER_MODE 431call with 432.Fa Dv PERIPH_CAP_TQING 433set in 434.Va xm_mode 435is mandatory to activate tagged queuing. 436.It Dv ASYNC_EVENT_RESET 437channel has been reset. No argument. 438HBA drivers have to issue 439.Dv ASYNC_EVENT_RESET events if they rely on the 440mid-layer for SCSI CHECK CONDITION handling. 441.El 442.Pp 443.It Fn scsipi_done "struct scsipi_xfer *xs" 444shall be called by the HBA when the xfer is complete, or when it needs to 445be requeued by the mid-layer. 446.Va error 447in the scsipi_xfer shall be set to one of the following: 448.Bl -tag -width xxxxxxxx -compact 449.It Dv XS_NOERROR 450xfer completed without error. 451.It Dv XS_SENSE 452Check the returned SCSI sense for the error. 453.It Dv XS_SHORTSENSE 454Check the ATAPI sense for the error. 455.It Dv XS_DRIVER_STUFFUP 456Driver failed to perform operation. 457.It Dv XS_RESOURCE_SHORTAGE 458Adapter resource shortage. The mid-layer will retry the command after some 459delay. 460.It Dv XS_SELTIMEOUT 461The device timed out while trying to send the command 462.It Dv XS_TIMEOUT 463The command was accepted by the device, but it didn't complete in allowed time. 464.It Dv XS_BUSY 465The mid-layer will check 466.Va status 467for additional details: 468.Bl -tag -width SCSI_QUEUE_FULL -compact 469.It Dv SCSI_CHECK 470SCSI check condition. The mid-layer will freeze the periph queue and issue 471a REQUEST SENSE command. If the HBA supports tagged queuing, it shall remove 472and requeue any command not yet accepted by the HBA (or at last make sure no 473more commands will be sent to the device before the REQUEST SENSE is complete). 474.It Dv SCSI_QUEUE_FULL 475The mid layer will adjust the periph's openings and requeue the command. 476.It Dv SCSI_BUSY 477The mid-layer will requeue the xfer after delay. 478.El 479.It Dv XS_RESET 480xfer destroyed by a reset; the mid-layer will requeue it. 481.It Dv XS_REQUEUE 482Ask the mid-layer to requeue this command immediately. 483.El 484.Pp 485The adapter should not reference an 486.Fa xfer 487once 488.Fn scsipi_done "xfer" 489has been called, unless the 490.Fa xfer 491had 492.Dv XS_CTL_POLL 493set. 494.Pp 495.Fn scsipi_done 496will call the 497.Fn adapt_request 498callback again only if called with 499.Fa xs->error 500set to 501.Dv XS_NOERROR , 502and 503.Fa xfer 504doesn't have 505.Dv XS_CTL_POLL 506set. All other error conditions are handled by a kernel thread 507(once the HBA's interrupt handler has returned). 508.It Fn scsipi_printaddr "struct scsipi_periph *periph" 509print a kernel message with the periph's name, in the form 510device(controller:channel:target:lun). 511.It Fn scsipi_channel_freeze "struct scsipi_channel *chan" "int count" 512Freeze the specified channel (requests are queued but not sent to HBA). The 513channel's freeze counter is increased by 514.Fa count . 515.It Fn scsipi_channel_thaw "struct scsipi_channel *chan" "int count" 516Decrement the channel's freeze counter by 517.Fa count 518and process the queue if the counter goes to 0. In order to preserve command 519ordering, HBA drivers should not call 520.Fn scsipi_channel_thaw 521before calling 522.Fn scsipi_done 523for all commands in the HBA's queue which need to be requeued. 524.It Fn scsipi_periph_timed_thaw "void *arg" 525Call 526.Fn scsipi_channel_thaw "arg" "1" . 527Intended to be used as 528.Xr callout 9 529callback. 530.It Fn scsipi_periph_freeze "struct scsipi_periph *periph" "int count" 531.It Fn scsipi_periph_thaw "struct scsipi_periph *periph" 532.It Fn scsipi_periph_timed_thaw "void *arg" 533Same as the channel counterparts, but only for one specific peripheral. 534.It Fn scsipi_target_detach "struct scsipi_channel *chan" "int target" "int lun" "int flags" 535detach the periph associated with this I_T_L nexus. Both 536.Fa target 537and 538.Fa lun 539may be wildcarded using the magic value -1. 540.Fa flags 541is passed to 542.Fn config_detach "" 543\&. 544Returns 0 if successfull, or error code if a device couldn't be removed. 545.It Fn scsipi_thread_call_callback "struct scsipi_channel *chan" "void (*callback) __P((struct scsipi_channel *, void *))" "void *arg" 546.Fn callback 547will be called with 548.Fa chan 549and 550.Fa arg 551as arguments, from the channel completion thread. The callback is run at 552splbio. 553.Fn scsipi_thread_call_callback 554will freeze the channel by one, it's up to the caller to thaw it when 555appropriate. returns 0 if the callback was properly recorded, or EBUSY if the 556channel has already a callback pending. 557.El 558.Sh EXAMPLES 559The best examples are existing HBA drivers. Most of them sit in the 560.Pa sys/dev/ic 561directory. 562.Sh FILES 563.Bl -tag -width sys/dev/atapiconf.h 564.It Pa sys/dev/scsiconf.h 565header file for use by SCSI HBA drivers 566.It Pa sys/dev/atapiconf.h 567header file for use by ATAPI HBA drivers 568.El 569.Pp 570Both header files include 571.Pa sys/dev/scsipiconf.h 572which contains most structure definitions, function prototypes and macros. 573.Sh AUTHORS 574The 575.Nm 576interface was designed and implemented by Jason R. Thorpe. Manuel Bouyer 577converted most drivers to the new interface. 578.Sh HISTORY 579The 580.Nm 581interface appeared in 582.Nx 1.6 . 583