iokit/IOKit/scsi/IOSCSIDevice_Reference.h

   1 /*
   2  * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * The contents of this file constitute Original Code as defined in and
   7  * are subject to the Apple Public Source License Version 1.1 (the
   8  * "License").  You may not use this file except in compliance with the
   9  * License.  Please obtain a copy of the License at
  10  * http://www.apple.com/publicsource and read it before using this file.
  11  *
  12  * This Original Code and all software distributed under the License are
  13  * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  14  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  15  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  16  * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
  17  * License for the specific language governing rights and limitations
  18  * under the License.
  19  *
  20  * @APPLE_LICENSE_HEADER_END@
  21  */
  22
  23
  24 /*!
  25 @header IOSCSIDevice_Reference.h
  26
  27 This header defines the IOSCSIDevice class.
  28
  29 The SCSI framework creates instances of this class to
  30 represent each valid SCSI device (target/lun) detected during
  31 SCSI bus scanning. When an instance of this class is registered with
  32 IOKit, the instance will be presented to clients which
  33 'match' the IOSCSIDevice class.
  34 */
  35
  36 /*!
  37 @typedef SCSITargetParms
  38 Parameter structure for get/setTargetParms
  39 @field transferPeriodpS
  40 Minimum SCSI synchronous transfer period allowed
  41 for this target in picoseconds (10E-12). For asynchronous data transfer,
  42 set this field to 0.
  43 @field transferOffset
  44 Maximum SCSI synchronous transfer offset allowed for this target in
  45 bytes. For asynchronous data transfer, set this field to 0.
  46 @field transferWidth
  47 Maximum SCSI bus width in bytes. Note: must be a
  48 power of 2.
  49 @field enableTagQueuing
  50 Setting enableTagQueuing to true enables tag queuing for SCSI Commands
  51 issued to the target.
  52 @field disableParity
  53 Set to (true) to disable parity checking on the
  54 SCSI bus for this target.
  55 */
  56 typedef struct SCSITargetParms {
  57     UInt32              transferPeriodpS;
  58     UInt32              transferOffset;
  59     UInt32              transferWidth;
  60
  61     bool                enableTagQueuing;
  62     bool                disableParity;
  63
  64     UInt32          reserved[16];
  65
  66 } SCSITargetParms;
  67
  68
  69 /*!
  70 @typedef SCSILunParms
  71 Parameter structure for get/setLunParms
  72 @field disableDisconnect
  73 Setting disableDisconnect to true disables SCSI disconnect for SCSI
  74 Commands issued to the target/lun pair.
  75 */
  76 typedef struct SCSILunParms {
  77     bool        disableDisconnect;
  78
  79     UInt32      reserved[16];
  80
  81 } SCSILunParms;
  82
  83
  84 /*!
  85 @enum SCSIClientMessage
  86 @discussion
  87 IOSCSIDevice notifies its client of significant 'events' by the IOService::message()
  88 api. When possible the client is notified of the event prior to any action taken. The
  89 client is responsible for managing the device queue for the IOSCSIDevice
  90 via the holdQueue(), releaseQueue(), flushQueue() and notifyIdle() api's. The client is also
  91 notified at the end of an 'event' by the corresponding message id with or'd with
  92 kClientMsgDone.
  93 @constant kClientMsgDeviceAbort
  94 A client initiated device abort is beginning.
  95 @constant kClientMsgDeviceReset
  96 A client initiated device reset is beginning.
  97 @constant kClientMsgBusReset
  98 An unsolicited bus reset has occurred.
  99 @constant kClientMsgDone
 100 This constant is or'd with one of the above message ids to indicate the
 101 client should complete processing of the corresponding event.
 102 */
 103 enum SCSIClientMessage {
 104     kClientMsgDeviceAbort               =  0x00005000,
 105     kClientMsgDeviceReset,
 106     kClientMsgBusReset,
 107
 108     kClientMsgDone                      = 0x80000000,
 109 };
 110
 111
 112 /*!
 113 @class IOSCSIDevice : public IOCDBDevice
 114 @abstract
 115 Class that describes a SCSI device (target/lun pair).
 116 @discussion
 117 The IOSCSIDevice class provides basic services
 118 to initialize and supervise a SCSI device. Once the device is
 119 initialized, the client will normally use the allocCommand() member
 120 function to create IOSCSICommand(s) to send SCSI CDBs to the target/lun.
 121 */
 122 class IOSCSIDevice : public IOCDBDevice
 123 {
 124 public:
 125
 126 /*!
 127 @function allocCommand
 128 @abstract
 129 Allocates a IOSCSICommand object for this device.
 130 @discussion
 131 The client uses the allocCommand() member function to allocate IOSCSICommand(s)
 132 for a IOSCSIDevice. The client then uses the member functions of
 133 the IOSCSICommand to initialize it and send it to the device. A completed IOSCSICommand
 134 may be reused for subsequent I/O requests or returned to the SCSI Family.
 135 @param scsiDevice
 136 Always specify kIOSCSIDevice.
 137 @param clientDataSize
 138 The client may indicate the size of a per-command data area for its own
 139 use.
 140
 141 Note: The amount of per-command storage allowed is under review. We
 142 anticipate that typical SCSI clients will need not more than 1024 bytes
 143 per command.
 144 */
 145 IOSCSICommand *allocCommand( IOSCSIDevice *scsiDevice, UInt32 clientDataSize = 0 );
 146
 147
 148 /*!
 149 @function setTargetParms
 150 @abstract
 151 Sets SCSI parameters that apply to all luns on a SCSI target device.
 152 @discussion
 153 This function will block until we attempt to set the
 154 requested parameters. It may not be called from the device's workloop context.
 155
 156 The SCSI Family will serialize accesses to the SCSI
 157 target so as not to disrupt commands in progress prior to processing a
 158 change of target parameters.
 159 @param targetParms
 160 Pointer to structure of type SCSITargetParms.
 161 */
 162 bool setTargetParms( SCSITargetParms *targetParms );
 163
 164
 165 /*!
 166 @function getTargetParms
 167 @abstract
 168 Gets the current target parameters.
 169 @discussion
 170 Returns the parameters currently in effect for the SCSI target.
 171 See setTargetParms().
 172 @param targetParms
 173 Pointer to structure of type SCSITargetParms.
 174 */
 175 void getTargetParms( SCSITargetParms *targetParms );
 176
 177
 178 /*!
 179 @function setLunParms
 180 @abstract
 181 Sets the logical unit parameters for this device.
 182 @discussion
 183 This function will block until we attempt to set the
 184 requested parameters. It may not be called from the device's workloop context.
 185
 186 The SCSI Family will serialize accesses to the SCSI
 187 target/lun so as not to disrupt commands in progress prior to processing a
 188 change of lun parameters.
 189 @param lunParms
 190 Pointer to structure of type SCSILunParms
 191 */
 192 bool setLunParms( SCSILunParms *lunParms );
 193
 194
 195 /*!
 196 @function getLunParms
 197 @abstract
 198 Gets the current logical unit parameters.
 199 @discussion
 200 Returns the parameters currently in effect for the SCSI target/lun.
 201 @param lunParms
 202 Pointer to structure of type SCSITargetParms
 203 */
 204 void getLunParms( SCSILunParms *lunParms );
 205
 206
 207 /*!
 208 @function abort
 209 @abstract
 210 Aborts all outstanding requests for the target/lun pair.
 211 @discussion
 212 If any I/O requests are currently active for the target/lun, an abort
 213 command is sent to the device and any active requests are completed.
 214
 215 Prior to abort processing beginning, the client will be notified via:
 216
 217 message( kClientMsgDeviceAbort );
 218
 219 When abort processing is completed, the client will be notified via:
 220
 221 message( kClientMsgDeviceAbort | kClientMsgDone );
 222
 223 The client is responsible for managing the pending work queue for
 224 the device when an abort request occurs. See holdQueue(), flushQueue(),
 225 notifyIdle() functions.
 226 */
 227 void abort();
 228
 229
 230 /*!
 231 @function reset
 232 @abstract
 233 Resets the SCSI target.
 234 @discussion
 235 Since a SCSI target may have multiple logical units (lun(s)) the
 236 reset() function may affect multiple IOSCSIDevice instances. Processing for
 237 each lun is similar.
 238
 239 Prior to reset processing beginning, the client will be notified via:
 240
 241 message( kClientMsgDeviceReset );
 242
 243 When reset processing is completed, the client will be notified via:
 244
 245 message( kClientMsgDeviceReset | kClientMsgDone );
 246
 247 The client is responsible for managing the pending work queue for
 248 the device when an abort request occurs. See holdQueue(), flushQueue(),
 249 notifyIdle() functions.
 250 */
 251 void reset();
 252
 253
 254 /*!
 255 @function getInquiryData
 256 @abstract Returns SCSI Inquiry data for the IOSCSIDevice.
 257 @discussion
 258 Inquiry data returned is from the results of the last SCSI bus probe.
 259 @param inquiryBuffer
 260 Pointer to a buffer to receive the Inquiry data.
 261 @param inquiryBufSize
 262 Size of the buffer supplied.
 263 @param inquiryDataSize
 264 Pointer to a UInt32 to receive the size of the Inquiry data actually
 265 returned.
 266 */
 267 void getInquiryData( void *inquiryBuffer, UInt32 inquiryBufSize, UInt32 *inquiryDataSize );
 268
 269
 270 /*!
 271 @function message
 272 @abstract
 273 IOService message function.
 274 @discussion
 275 IOSCSIDevice notifies its client of significant 'events' by the IOService::message()
 276 api. When possible the client is notified of the event prior to any action taken. The
 277 client is responsible for managing the device queue for the IOSCSIDevice
 278 via the holdQueue(), releaseQueue(), flushQueue() and notifyIdle() api's.
 279
 280 Any return codes provided by the client are ignored.
 281 @param message-id
 282 Message id's for IOSCSIDevice are defined by enum SCSIClientMessage
 283 @param provider
 284 Pointer to the IOSCSIDevice reporting the event.
 285 @param argument
 286 Unused.
 287 */
 288 IOReturn message( UInt32 type, IOService * provider, void * argument = 0 );
 289
 290
 291 /*!
 292 @function open
 293 @abstract
 294 IOService open function
 295 @discussion
 296 A client should open a IOSCSIDevice prior to accessing it. Only one open is allowed
 297 per device.
 298 @param client
 299 Pointer to the IOSCSI device the client is opening.
 300 @param options
 301 There are currently no options defined by the SCSI Family.
 302 @param arg
 303 Unused. Omit or specify 0.
 304 */
 305 bool open( IOService *client, IOOptionBits options = 0, void *arg = 0 );
 306
 307
 308 /*!
 309 @function close
 310 @abstract
 311 IOService close function
 312 @discussion
 313 A client must close a IOSCSIDevice if the client plans no further accesses to it.
 314 @param client
 315 Pointer to the IOSCSI device the client is closing.
 316 @param options
 317 There are currently no options defined by the SCSI Family.
 318 */
 319 void close( IOService *client, IOOptionBits     options = 0 );
 320
 321
 322 /*!
 323 @function holdQueue
 324 @abstract
 325 Suspends sending additional IOSCSICommands to the target/lun.
 326 @discussion
 327 holdQueue() may only be called from the IOSCSIDevice workloop. The client
 328 is guaranteed to be running in this context during a message() notification.
 329
 330 holdQueue() has no effect on commands already passed to the host adapter. One
 331 or more commands may complete after the queue is held. See notifyIdle()
 332 @param queueType
 333 Perform action on the indicated queue. See enum SCSIQueueType in IOSCSICommand.
 334 */
 335 holdQueue( UInt32 queueType );
 336
 337
 338 /*!
 339 @function flushQueue
 340 @abstract
 341 Returns any commands on the IOSCSIDevice's pending work queue.
 342 @discussion
 343 flushQueue() may only be called from the IOSCSIDevice workloop. This is
 344 guaranteed to be the case after a IOSCSICommand completion of after a
 345 message() notification.
 346
 347 All pending command are completed prior to flushQueue() returning to the caller.
 348
 349 flushQueue() has no effect on commands already passed to the host adapter. One
 350 or more commands may complete after the queue is flushed. See notifyIdle().
 351 @param queueType
 352 Perform action on the indicated queue. See enum SCSIQueueType in IOSCSICommand.
 353 @param rc
 354 The return code of any flushed commands is set to (rc).
 355 */
 356 void flushQueue( UInt32 queueType, IOReturn rc );
 357
 358
 359 /*!
 360 @function notifyIdle
 361 @abstract
 362 Notifies the client when all active commands on a SCSI device have completed.
 363 @discussion
 364 notifyIdle() may only be called from the IOSCSIDevice workloop. This is guaranteed
 365 to be the case after a IOSCSICommand completion of after a message() notification.
 366
 367 Only one notifyIdle() call may be active. Any outstanding notifyIdle() calls may
 368 be cancelled by calling notifyIdle() with no parameters.
 369 @param target
 370 Object to receive the notification. Normally the client's (this) pointer.
 371 @param callback
 372 Pointer to a callback routine of type CallbackFn.
 373 @param refcon
 374 Pointer to client's private data.
 375 */
 376 void notifyIdle( void *target, Callback callback, void *refcon );
 377
 378
 379 /*!
 380 @function releaseQueue
 381 @abstract
 382 Resumes sending IOSCSICommands to the IOSCSIDevice.
 383 @discussion
 384 If the device queue was not held, releaseQueue() has no effect.
 385
 386 releaseQueue() may only be called from the IOSCSIDevice workloop. This is guaranteed
 387 to be the case after a IOSCSICommand completion of after a message() notification.
 388 @param queueType
 389 Perform action on the indicated queue. See enum SCSIQueueType in IOSCSICommand.
 390 */
 391 void releaseQueue( UInt32 queueType );
 392
 393
 394 /*!
 395 @function getWorkLoop
 396 @abstract
 397 Returns the IOWorkLoop object that services this IOSCSIDevice.
 398 */
 399 IOWorkloop *getWorkLoop();
 400
 401 }