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