1.\" $NetBSD: scsipi.9,v 1.10 2002/05/15 11:17:32 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 \*[Lt]dev/scsipi/atapiconf.h\*[Gt] 42.Fd #include \*[Lt]dev/scsipi/scsiconf.h\*[Gt] 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)(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 \*[Lt]dev/scsipi/scsipiconf.h\*[Gt] 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. This request is called from 335the kernel completion thread. 336.Fa arg 337must be ignored. 338.It Dv ADAPTER_REQ_SET_XFER_MODE 339set the xfer mode for a for I_T Nexus. This will be called once all 340LUNs of a target have been probed. 341.Fa arg 342points to a 343.Va struct scsipi_xfer_mode 344defined as follows: 345.Bl -tag -width int_xm_target -compact 346.It Va int xm_target 347target for I_T Nexus 348.It Va int xm_mode 349bitmask of device capabilities 350.It Va int xm_period 351sync period 352.It Va int xm_offset 353sync offset 354.El 355.Pp 356.Va xm_period 357and 358.Va xm_offset 359shall be ignored for 360.Dv ADAPTER_REQ_SET_XFER_MODE . 361.Va xm_mode 362holds the following bits: 363.Bl -tag -width xxxxxxxx -compact 364.It Dv PERIPH_CAP_SYNC 365ST synchronous transfers 366.It Dv PERIPH_CAP_WIDE16 367ST 16 bit wide transfers 368.It Dv PERIPH_CAP_WIDE32 369ST 32 bit wide transfers 370.It Dv PERIPH_CAP_DT 371DT transfers 372.It Dv PERIPH_CAP_TQING 373tagged queueing 374.El 375Whenever the xfer mode changes, the driver should call 376.Fn scsipi_async_event 377to notify the mid-layer. 378.El 379.Pp 380.Fn adapt_request 381may be called from interrupt context. 382.It Fn adapt_minphys 383pointer to the driver's minphys function. If the driver can handle 384transfers of size 385.Dv MAXPHYS , 386this can point to 387.Fn minphys . 388.It Fn adapt_ioctl 389ioctl function for the channel. The only ioctl supported at this level is 390.Dv SCBUSIORESET 391for which the HBA driver shall issue a SCSI reset on the channel. 392.It int Fn adapt_enable "struct device *dev" "int enable" 393Disable the adapter if 394.Va enable 395is zero, or enable it if non-zero. Returns 0 if operation is successful, 396or error from 397.Pa \*[Lt]sys/errno.h\*[Gt] . 398This callback is optional, and is useful mostly for hot-plug devices. 399For example, this callback would power on or off 400the relevant PCMCIA socket for a PCMCIA controller. 401.It int Fn adapt_getgeom "struct scsipi_periph *periph" "struct disk_parms *params" "u_long sectors" 402Optional callback, used by high-level drivers to get the fictitious geometry 403used by the controller's firmware for the specified periph. Returns 0 if 404successful. See adaptec drivers for details. 405.It int Fn adapt_accesschk "struct scsipi_periph *periph" "struct scsipi_inquiry_pattern *inqbuf" 406Optional callback; if present the mid-layer uses it to check if it can 407attach a driver to the specified periph. If the callback returns a non-zero 408value, the periph is ignored by the 409.Nm 410code. This callback is used by adapters which want to drive some devices 411themselves, for example hardware RAID controllers. 412.It Fn scsipi_async_event "struct scsipi_channel *chan" "scsipi_async_event_t event" "void *arg" 413Asynchronous event notification for the mid-layer. 414.Fa event 415can be one of: 416.Bl -tag -width xxxxxxxx -compact 417.It Dv ASYNC_EVENT_MAX_OPENINGS 418set max openings for a periph. Argument is a 419.Va struct scsipi_max_openings 420with at least the following members: 421.Bl -tag -width xxxxxxxx -compact 422.It Va int mo_target 423.It Va int mo_lun 424.It Va int mo_openings 425.El 426.Pp 427Not all periphs may allow openings to increase; if not allowed the request is 428silently ignored. 429.It Dv ASYNC_EVENT_XFER_MODE 430update the xfer mode for an I_T nexus. Argument is a 431.Va struct scsipi_xfer_mode 432properly filled in. An 433.Fa Dv ASYNC_EVENT_XFER_MODE 434call with 435.Fa Dv PERIPH_CAP_TQING 436set in 437.Va xm_mode 438is mandatory to activate tagged queuing. 439.It Dv ASYNC_EVENT_RESET 440channel has been reset. No argument. 441HBA drivers have to issue 442.Dv ASYNC_EVENT_RESET events if they rely on the 443mid-layer for SCSI CHECK CONDITION handling. 444.El 445.Pp 446.It Fn scsipi_done "struct scsipi_xfer *xs" 447shall be called by the HBA when the xfer is complete, or when it needs to 448be requeued by the mid-layer. 449.Va error 450in the scsipi_xfer shall be set to one of the following: 451.Bl -tag -width xxxxxxxx -compact 452.It Dv XS_NOERROR 453xfer completed without error. 454.It Dv XS_SENSE 455Check the returned SCSI sense for the error. 456.It Dv XS_SHORTSENSE 457Check the ATAPI sense for the error. 458.It Dv XS_DRIVER_STUFFUP 459Driver failed to perform operation. 460.It Dv XS_RESOURCE_SHORTAGE 461Adapter resource shortage. The mid-layer will retry the command after some 462delay. 463.It Dv XS_SELTIMEOUT 464The device timed out while trying to send the command 465.It Dv XS_TIMEOUT 466The command was accepted by the device, but it didn't complete in allowed time. 467.It Dv XS_BUSY 468The mid-layer will check 469.Va status 470for additional details: 471.Bl -tag -width SCSI_QUEUE_FULL -compact 472.It Dv SCSI_CHECK 473SCSI check condition. The mid-layer will freeze the periph queue and issue 474a REQUEST SENSE command. If the HBA supports tagged queuing, it shall remove 475and requeue any command not yet accepted by the HBA (or at last make sure no 476more commands will be sent to the device before the REQUEST SENSE is complete). 477.It Dv SCSI_QUEUE_FULL 478The mid layer will adjust the periph's openings and requeue the command. 479.It Dv SCSI_BUSY 480The mid-layer will requeue the xfer after delay. 481.El 482.It Dv XS_RESET 483xfer destroyed by a reset; the mid-layer will requeue it. 484.It Dv XS_REQUEUE 485Ask the mid-layer to requeue this command immediately. 486.El 487.Pp 488The adapter should not reference an 489.Fa xfer 490once 491.Fn scsipi_done "xfer" 492has been called, unless the 493.Fa xfer 494had 495.Dv XS_CTL_POLL 496set. 497.Pp 498.Fn scsipi_done 499will call the 500.Fn adapt_request 501callback again only if called with 502.Fa xs-\*[Gt]error 503set to 504.Dv XS_NOERROR , 505and 506.Fa xfer 507doesn't have 508.Dv XS_CTL_POLL 509set. All other error conditions are handled by a kernel thread 510(once the HBA's interrupt handler has returned). 511.It Fn scsipi_printaddr "struct scsipi_periph *periph" 512print a kernel message with the periph's name, in the form 513device(controller:channel:target:lun). 514.It Fn scsipi_channel_freeze "struct scsipi_channel *chan" "int count" 515Freeze the specified channel (requests are queued but not sent to HBA). The 516channel's freeze counter is increased by 517.Fa count . 518.It Fn scsipi_channel_thaw "struct scsipi_channel *chan" "int count" 519Decrement the channel's freeze counter by 520.Fa count 521and process the queue if the counter goes to 0. In order to preserve command 522ordering, HBA drivers should not call 523.Fn scsipi_channel_thaw 524before calling 525.Fn scsipi_done 526for all commands in the HBA's queue which need to be requeued. 527.It Fn scsipi_periph_timed_thaw "void *arg" 528Call 529.Fn scsipi_channel_thaw "arg" "1" . 530Intended to be used as 531.Xr callout 9 532callback. 533.It Fn scsipi_periph_freeze "struct scsipi_periph *periph" "int count" 534.It Fn scsipi_periph_thaw "struct scsipi_periph *periph" 535.It Fn scsipi_periph_timed_thaw "void *arg" 536Same as the channel counterparts, but only for one specific peripheral. 537.It Fn scsipi_target_detach "struct scsipi_channel *chan" "int target" "int lun" "int flags" 538detach the periph associated with this I_T_L nexus. Both 539.Fa target 540and 541.Fa lun 542may be wildcarded using the magic value -1. 543.Fa flags 544is passed to 545.Fn config_detach "" 546\&. 547Returns 0 if successfull, or error code if a device couldn't be removed. 548.It Fn scsipi_thread_call_callback "struct scsipi_channel *chan" "void (*callback)(struct scsipi_channel *, void *)" "void *arg" 549.Fn callback 550will be called with 551.Fa chan 552and 553.Fa arg 554as arguments, from the channel completion thread. The callback is run at 555splbio. 556.Fn scsipi_thread_call_callback 557will freeze the channel by one, it's up to the caller to thaw it when 558appropriate. Returns 0 if the callback was properly recorded, or EBUSY if the 559channel has already a callback pending. 560.El 561.Sh FILES 562.Bl -tag -width sys/dev/atapiconf.h 563.It Pa sys/dev/scsiconf.h 564header file for use by SCSI HBA drivers 565.It Pa sys/dev/atapiconf.h 566header file for use by ATAPI HBA drivers 567.El 568.Pp 569Both header files include 570.Pa sys/dev/scsipiconf.h 571which contains most structure definitions, function prototypes and macros. 572.Sh EXAMPLES 573The best examples are existing HBA drivers. Most of them sit in the 574.Pa sys/dev/ic 575directory. 576.Sh HISTORY 577The 578.Nm 579interface appeared in 580.Nx 1.6 . 581.Sh AUTHORS 582The 583.Nm 584interface was designed and implemented by Jason R. Thorpe. Manuel Bouyer 585converted most drivers to the new interface. 586