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