![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to IOSCSIController_Reference.h CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Apple XNU] / XNU / iokit / IOKit / scsi|
Return to IOSCSIController_Reference.h CVS log | Up to [Apple XNU] / XNU / iokit / IOKit / scsi |
1.1 root 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 IOSCSIController_Reference.h
26:
27: This header defines the IOSCSIController class.
28:
29: IOSCSIController provides the superclass for SCSI host
30: adapter drivers.
31:
32: Drivers are instantiated based on their 'personality' entry matching
33: their adapter's OpenFirmware device tree entry. When a match occurs,
34: the driver's class is instantiated. Since the driver is written as a
35: subclass of IOSCSIController, an instance of the SCSI Family is automatically
36: instantiated.
37: */
38:
39:
40: /*!
41: @typedef SCSIControllerInfo
42: Parameter structure passed for configure() function.
43: @field initiatorId
44: The SCSI address of your host adapter. Usually 7 (decimal).
45: @field maxTargetsSupported
46: The number of targets you controller supports. Typically 8 or 16.
47: @field maxLunsSupported
48: The number of logical units per target your controller supports.
49: Typically 8.
50: @field minTransferPeriodpS
51: The minimum synchronous data transfer period in picoseconds your
52: controller supports.
53: @field maxTransferOffset
54: The maximum synchronous data offset your controller supports in bytes.
55: @field maxTransferWidth
56: The maximum data SCSI bus width your controller supports in bytes. Must
57: be a power of 2.
58: @field maxCommandsPerController
59: The maximum number of outstanding commands your controller supports
60: across all targets and luns. Set to 0 if there is no controller limit in
61: this category.
62: @field maxCommandsPerTarget
63: The maximum number of outstanding commands your controller supports on a
64: given target. Set to 0 if there is no controller limit in this category.
65: @field maxCommandsPerLun
66: The maximum number of outstanding commands your controller supports on a
67: given lun. Set to 0 if there is no controller limit in this category.
68: @field tagAllocationMethod
69: Controls whether tags are allocated on a per Lun, per Target or per
70: Controller basis. See enum SCSITagAllocation.
71: @field maxTags
72: The maximum number of tags allocated to each Lun, Target or Controller
73: depending on the tagAllocationMethod setting.
74: @field targetPrivateDataSize
75: IOSCSIController will optionally allocate per-target storage for your
76: driver based on the setting of this field. The amount of storage needed
77: is specified in bytes.
78: @field lunPrivateDataSize
79: IOSCSIController will optionally allocate per-lun storage for your
80: driver based on the setting of this field. The amount of storage needed
81: is specified in bytes.
82: @field commandPrivateDataSize
83: IOSCSIController will optionally allocate per-command storage for your
84: driver based on the setting of this field. The amount of storage needed
85: is specified in bytes.
86:
87: Note: The amount of per-command storage allowed is under review. We
88: anticipate that typical SCSI controllers will need not more than 1024
89: bytes per command.
90: @field disableCancelCommands
91: Subclasses of IOSCSIController which do their own management of
92: aborts/resets can set this field to true to avoid receiving
93: cancelCommand() requests.
94: */
95: typedef struct SCSIControllerInfo {
96: UInt32 initiatorId;
97:
98: UInt32 maxTargetsSupported;
99: UInt32 maxLunsSupported;
100:
101: UInt32 minTransferPeriodpS;
102: UInt32 maxTransferOffset;
103: UInt32 maxTransferWidth;
104:
105: UInt32 maxCommandsPerController;
106: UInt32 maxCommandsPerTarget;
107: UInt32 maxCommandsPerLun;
108:
109: UInt32 tagAllocationMethod;
110: UInt32 maxTags;
111:
112: UInt32 targetPrivateDataSize;
113: UInt32 lunPrivateDataSize;
114: UInt32 commandPrivateDataSize;
115:
116: bool disableCancelCommands;
117:
118: UInt32 reserved[64];
119:
120: } SCSIControllerInfo;
121:
122:
123: /*!
124: @enum SCSITagAllocation
125: @discussion
126: This enum defines how SCSI tags are allocated.
127: @constant kTagAllocationNone
128: This controller does not support tag queuing.
129: @constant kTagAllocationPerLun
130: Each SCSI Lun has its own private tag pool containing
131: (maxTags) SCSI tags.
132: @constant kTagAllocationPerTarget
133: Each SCSI Target has its own private tag pool contain
134: (maxTags) SCSI tags. Luns connected to this target
135: allocate tags from this pool.
136: @constant kTagAllocationPerController
137: The controller has a global tag pool containing (maxTags)
138: SCSI tags. This pool is shared by all Luns connected to
139: this controller.
140: */
141: enum {
142: kTagAllocationNone = 0,
143: kTagAllocationPerLun,
144: kTagAllocationPerTarget,
145: kTagAllocationPerController,
146: };
147:
148:
149: /*!
150: @class IOSCSIController : public IOService
151: @abstract
152: Superclass for SCSI host adapter drivers
153: @discussion
154: The IOSCSIController class provides a number of services to simplify
155: writing a driver for your host adapter.
156:
157: Specifically, the class provides the following features:
158:
159: 1. Complete request scheduling semantics.
160:
161: The IOSCSIController class manages request queues on behalf of its
162: subclasses. It tracks all requests submitted to its subclasses,
163: including managing timeouts, aborts and request cancellations.
164:
165: 2. Request Sense scheduling
166:
167: Subclasses of IOSCSIController do not need to implement
168: auto-request-sense functionality. Your driver can use the default
169: handling in the super class.
170:
171: 3. Storage management.
172:
173: The IOSCSIController subclass provides per-request private storage areas
174: for your subclass.
175:
176: 4. Resource management.
177:
178: The IOSCSIController subclass will manage the number of outstanding
179: commands submitted to your subclass on a per-controller and per-lun
180: basis.
181: */
182: @class IOSCSIController : public IOService
183: {
184: public:
185:
186:
187: /*!
188: @function configure
189: @abstract
190: Driver configuration/initialization request.
191: @discussion
192: The configure() member function is the first call your subclass will
193: receive. You should provide the information requested in the
194: SCSIControllerInfo structure and enable your hardware for operation.
195: If your driver initialized successfully, you should return true, otherwise,
196: your driver should return false.
197: @param provider
198: Pointer to an object (usually IOPCIDevice) which represents the bus of
199: your device is attached to . Typically your driver will use functions
200: supplied by this object to access PCI space on your hardware. See
201: IOPCIDevice for a description of PCI services.
202: @param controllerInfo
203: Pointer to a SCSIControllerInfo structure. Your driver should provide
204: the information requested in this structure prior to returning from
205: the configure() call.
206: */
207: bool configure( IOService *provider, SCSIControllerInfo *controllerInfo );
208:
209:
210: /*!
211: @function executeCommand
212: @abstract
213: Execute a IOSCSICommand.
214: @discussion
215: The executeCommand() function is called for all 'routine' I/O requests
216: including abort requests. The driver is passed a pointer to an
217: IOSCSICommand object. The driver obtains information about the I/O
218: request by using function calls provided by the IOSCSICommand
219: class.
220: @param scsiCommand
221: Pointer to a IOSCSICommand. See IOSCSICommand for more information.
222: */
223: void executeCommand( IOSCSICommand *scsiCommand );
224:
225:
226: /*!
227: @function cancelCommand
228: @abstract
229: Cancels a IOSCSICommand previously submitted to the driver.
230: @discussion
231: The cancelCommand() function is called to inform your subclass to force
232: completion of a SCSI command.
233:
234: Your subclass should call the getOriginalCmd() to determine the command
235: to complete.
236:
237: After calling complete() on the original command, you should complete
238: the IOSCSICommand passed to the cancelCommand() function
239:
240: Note: When a cancelCommand is issued, your subclass may presume that any
241: activity to remove an active command from the SCSI Target, i.e. (abort
242: tag/abort) has already occurred.
243: @param scsiCommand
244: Pointer to a IOSCSICommand. See IOSCSICommand for more information.
245: */
246: void cancelCommand( IOSCSICommand *scsiCommand );
247:
248:
249: /*!
250: @function resetCommand
251: @abstract
252: Request the driver issue a SCSI Bus reset.
253: @discussion
254: The resetCommand() function indicates you should do a SCSI Bus Reset.
255: After issuing the reset you should complete to IOSCSICommand passed.
256:
257: Note: After you report the IOSCSICommand Reset complete, you will
258: receive cancelCommand() requests for all outstanding commands.
259: @param scsiCommand
260: Pointer to a IOSCSICommand. See IOSCSICommand for more information.
261: */
262: void resetCommand( IOSCSICommand *scsiCommand );
263:
264:
265: /*!
266: @function resetOccurred
267: @abstract
268: Inform the IOSCSIController class of an unsolicited SCSI Bus reset.
269: @discussion
270: Your subclass should call this function if
271: you detect a target initiated bus reset, or need to do an unplanned SCSI
272: Bus Reset as part of adapter error recovery.
273:
274: Note: After you call the resetOccurred() function, you will receive
275: cancelCommand() requests for all outstanding IOSCSICommand(s).
276: */
277: void resetOccurred();
278:
279: /*!
280: @function rescheduleCommand
281: @abstract
282: Return a IOSCSICommand for rescheduling.
283: @discussion
284: If your subclass function cannot start processing an otherwise
285: acceptable IOSCSICommand due to resource constraints, i.e. MailBox full,
286: lost SCSI Bus arbitration, you may have the IOSCSICommand rescheduled by
287: calling rescheduleCommand(). A IOSCSICommand passed to this function
288: should be treated as 'complete', i.e. you should make no further
289: accesses to it.
290:
291: Note: If you cannot process further commands, you should call the
292: disableCommands() function to prevent receiving additional commands
293: until you are ready to accept them.
294: @param scsiCommand
295: Pointer to IOSCSICommand your driver needs to reschedule.
296: */
297: void rescheduleCommand( IOSCSICommand *scsiCommand );
298:
299:
300: /*!
301: @function disableCommands
302: @abstract
303: Suspend sending I/O commands to your driver.
304: @discussion
305: In cases where your executeCommand() member function cannot accept
306: commands, you may disable further calls by invoking disableCommands().
307: Use enableCommands() to resume receiving commands.
308:
309: Note: The resetCommand() and cancelCommands() entry points are not
310: affected by the use of this function.
311:
312: Note: The default timeout for disableCommands() is 5s. If this timeout
313: is exceeded the IOSCSIController class will call your driver's
314: disableTimeoutOccurred() function. The default action of this function
315: is to issue a SCSI Bus Reset by calling your driver's resetCommand()
316: function.
317: @param timeoutmS
318: Your driver may override the default timeout
319: by specifying a timeout value in milliseconds.
320: */
321: void disableCommands( UInt32 timeoutmS );
322:
323:
324: /*!
325: @function enableCommands
326: @abstract
327: Resume sending I/O commands to your driver.
328: @discussion
329: Resumes sending I/O commands to your driver that were previously suspended
330: by calling disableCommands().
331: */
332: void enableCommands();
333:
334: /*!
335: @function disableTimeoutOccurred
336: @abstract
337: Indicates your driver has suspended commands too long.
338: @discussion
339: The IOSCSIController superclass will timeout disableCommand() requests
340: to preclude the possibility of a hung SCSI bus. If a timeout occurs,
341: then disableTimeoutOccurred() will be called. The default action of this
342: routine is to do a SCSI Bus Reset by calling resetCommand(). Your
343: subclass may choose to modify the default behavior of this routine to do
344: additional adapter specific error recovery.
345: */
346: void disableTimeoutOccurred();
347:
348:
349: /*!
350: @function findCommandWithNexus
351: @abstract
352: Locate an active IOSCSICommand using target/lun/tag values.
353: @discussion
354: Your subclass can use this function to search for an active
355: IOSCSICommand by providing the target/lun/tag values for the command. In
356: the case of a non-tagged command the second parameter must either be
357: omitted or set to -1.
358:
359: An unsuccessful search will return 0.
360: @param targetLun
361: Structure of type SCSITargetLun, initialized to the target/lun value you
362: wish to search for.
363: @param tagValue
364: Optional tag value you wish to search for.
365: */
366: IOSCSICommand *findCommandWithNexus( SCSITargetLun targetLun, UInt32 tagValue = (UInt32) -1 );
367:
368: /*!
369: @function allocateTarget
370: @abstract
371: Notifies driver of allocation of per-Target resources.
372: @discussion
373: Your driver will be called at its allocateTarget() function when a target is about
374: to be probed. The your driver should initialize its per-target data at this time.
375: If the subclass wishes to prevent probing of this target, it should return false
376: as the result of this function call.
377:
378: This is an optional function. Your driver is not required to implement it.
379: @param targetLun
380: SCSITargetLun structure containing the SCSI Id of the target that is about to be
381: allocated.
382: */
383: bool allocateTarget( SCSITargetLun targetLun );
384:
385:
386: /*!
387: @function deallocateTarget
388: @abstract
389: Notifies driver that target resources will be deallocated.
390: @discussion
391: Your driver will be called at its deallocateTarget() function when a target is about
392: deallocated. The your driver must insure that there will be no further access to
393: the per-target data allocated to this target.
394:
395: This is an optional function. Your driver is not required to implement it.
396: @param targetLun
397: SCSITargetLun structure containing the SCSI Id of the target that is about to be
398: deallocated.
399: */
400: bool deallocateTarget( SCSITargetLun targetLun );
401:
402:
403: /*!
404: @function allocateLun
405: @abstract
406: Notifies driver of allocation of per-Lun resources.
407: @discussion
408: Your driver will be called at its allocateLun() function when a Lun is about
409: to be probed. The your driver should initialize its per-lun data at this time.
410: If the subclass wishes to prevent probing of this lun, it should return false
411: as the result of this function call.
412:
413: This is an optional function. Your driver is not required to implement it.
414: @param targetLun
415: SCSITargetLun structure containing the SCSI Id of the target/lun that is about to be
416: allocated.
417: */
418: bool allocateLun( SCSITargetLun targetLun );
419:
420:
421: /*!
422: @function deallocateLun
423: @abstract
424: Notifies driver of deallocation of per-Lun resources.
425: @discussion
426: Your driver will be called at its deallocateLun() function when a Lun is about
427: deallocated. The your driver must insure that there will be no further access to
428: the per-lun data allocated to this lun.
429:
430: This is an optional function. Your driver is not required to implement it.
431: @param targetLun
432: SCSITargetLun structure containing the SCSI Id of the target/lun that is about to be
433: deallocated.
434: */
435: bool allocateLun( SCSITargetLun targetLun );
436:
437:
438: /*!
439: @function getTargetData
440: @abstract
441: Obtains a pointer to per-Target data allocated by IOSCSIController.
442: @discussion
443: This function returns a pointer to per-Target workarea allocated for
444: your driver's use. The size of this area must be specified in the
445: during the configure() function. See struct SCSIControllerInfo,
446: field targetDataSize.
447: @param targetLun
448: SCSITargetLun structure containing the SCSI Id of the target who's
449: workarea you are requesting a pointer to.
450: */
451: void *getTargetData( SCSITargetLun targetLun );
452:
453:
454: /*!
455: @function getLunData
456: @abstract
457: Obtains a pointer to per-Lun data allocated by IOSCSIController.
458: @discussion
459: This function returns a pointer to per-Lun workarea allocated for
460: your driver's use. The size of this area must be specified
461: during the configure() function. See struct SCSIControllerInfo,
462: field lunDataSize.
463: */
464: void *getLunData( SCSITargetLun targetLun );
465:
466:
467: /*!
468: @function getWorkLoop
469: @abstract
470: Returns the IOWorkLoop object that services your driver.
471: */
472: IOWorkloop *getWorkLoop();
473:
474:
475: }
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.